@greenpandastudios/aug-cli 0.20.1 → 0.21.0

package/src/checker.js

@@ -15,6 +15,7 @@ import { jsonDataType } from "./schemas.js";
 import { htmlTags, htmlVoidTags, htmlAttribute, htmlUrlAttributes } from "./html.js";
 import { generateOpenApi } from "./openapi.js";
 import { httpPolicyNames, httpPolicyOptions, checkHttpPolicy } from "./http-policies.js";
+import { nativeDeclarations } from "./native-declarations.js";
 export { tyName } from "./types.js";
 const builtinNames = new Set(Object.keys(builtinTypes));
 const errorTy = { id: 'error', name: '<error>', kind: 'error', args: [], nullable: false };
@@ -46,6 +47,7 @@ class Checker {
     markupCalls = new WeakMap();
     actions = new Map();
     httpPolicies = new Map();
+    native;
     bindingByKey = new Map();
     constructorFreshness = new Map();
     constraintStack = new Set();
@@ -53,7 +55,7 @@ class Checker {
     inferring = false;
     inferenceChanged = false;
     changingInference = new Set();
-    constructor(project) { this.project = project; this.diagnostics = [...project.diagnostics]; }
+    constructor(project) { this.project = project; this.native = nativeDeclarations(project); this.diagnostics = [...project.diagnostics, ...this.native.diagnostics]; }
     check() {
         // Make inherited default bodies visible to forward calls during inference.
         this.inferring = true;
@@ -174,10 +176,16 @@ class Checker {
             for (const def of this.project.definitions.values())
                 if (served.has(def.id) && def.node.kind === 'function' && def.node.endpoint?.path === '/__aug/actions.js')
                     this.report(def.node.span, '/__aug/actions.js is reserved for HTTP action transport', 'HTTP');
+        for (const [node, layers] of this.interceptorPlans)
+            if (node.kind === 'class') {
+                for (const [index, layer] of layers.entries())
+                    layer.constructorResultFresh =
+                        layers.slice(index + 1).every(inner => this.layerReturnsFresh(inner));
+            }
         return { project: this.project, diagnostics: this.diagnostics, bindings: this.bindings,
             expressionTypes: this.expressionTypes, defaults: this.defaults, callPlans: this.callPlans,
             interceptorPlans: this.interceptorPlans, effectContracts: this.effectContracts, callableContracts: this.callableContracts, constructorContracts: this.constructorContracts,
-            expressionOrigins: this.expressionOrigins, scopes: this.scopes, markupCalls: this.markupCalls, actions: this.actions, httpPolicies: this.httpPolicies };
+            expressionOrigins: this.expressionOrigins, scopes: this.scopes, markupCalls: this.markupCalls, actions: this.actions, httpPolicies: this.httpPolicies, native: this.native };
     }
     isStatement(item) {
         return ['expr', 'assign', 'return', 'throw', 'if', 'while', 'for', 'destructure', 'match', 'try', 'unsafe', 'borrow', 'scope', 'freeze', 'serve', 'lock', 'yield'].includes(item.kind);
@@ -323,6 +331,9 @@ class Checker {
                 const args = ref.args.map(arg => this.resolveType(arg, file, params, validateConstraints));
                 if (ref.name !== 'Task' && args.some(arg => arg.id === 'builtin:void'))
                     this.report(ref.span, 'Collections cannot contain void', 'COLLECTION');
+                const containsResource = (type) => type.kind === 'resource' || type.args.some(containsResource);
+                if (args.some(containsResource))
+                    this.report(ref.span, 'Native resources require individual own bindings; managed collections cannot retain them', 'OWN');
                 return { ...builtin(ref.name), args,
                     nullable: ref.nullable, optional: ref.optional };
             }
@@ -427,6 +438,8 @@ class Checker {
             this.resolveType(param.type, file, params);
         }
         this.returnType(fn, file, params);
+        if (this.returnType(fn, file, params).kind === 'resource' && fn.returnOwnership !== 'own')
+            this.report(fn.span, 'A native resource return must declare returns own', 'OWN');
         if (fn.endpoint) {
             const endpoint = fn.endpoint;
             if (!/^[A-Z]+$/.test(endpoint.method))
@@ -482,22 +495,65 @@ class Checker {
                 this.report(thrown.span, `Thrown type ${typeName(thrown)} must implement Error`);
         }
         if (fn.externC) {
-            if (fn.nativePure && (fn.uses?.length || fn.changes?.length))
-                this.report(fn.span, 'A pure native declaration cannot declare effects', 'FFI');
-            if (fn.params.some(param => param.injected))
-                this.report(fn.span, 'extern C declarations cannot use resolve parameters', 'FFI');
-            if (fn.typeParams.length || fn.throws.length && !fn.valueAbi)
-                this.report(fn.span, 'extern C functions cannot be generic or declare unless errors', 'FFI');
-            if (fn.returnOwnership === 'own' || fn.params.some(param => param.ownership !== 'managed'))
-                this.report(fn.span, 'extern C functions cannot transfer AugScript ownership', 'FFI');
-            for (const type of fn.valueAbi ? [] : [...fn.params.map(p => p.type), fn.returns]) {
-                if (!['int', 'c_int', 'float', 'bool', 'string', 'void'].includes(type.name) || type.args.length || type.nullable)
-                    this.report(type.span, `Type ${typeName(type)} is not supported at the C FFI boundary`, 'FFI');
+            const native = this.native.functions.get(fn);
+            if (native)
+                this.checkNativeSignature(fn, file, native);
+            else {
+                if (fn.nativePure && (fn.uses?.length || fn.changes?.length))
+                    this.report(fn.span, 'A pure native declaration cannot declare effects', 'FFI');
+                if (fn.params.some(param => param.injected))
+                    this.report(fn.span, 'extern C declarations cannot use resolve parameters', 'FFI');
+                if (fn.typeParams.length || fn.throws.length && !fn.valueAbi)
+                    this.report(fn.span, 'extern C functions cannot be generic or declare unless errors', 'FFI');
+                if (fn.returnOwnership === 'own' || fn.params.some(param => param.ownership !== 'managed'))
+                    this.report(fn.span, 'extern C functions cannot transfer AugScript ownership', 'FFI');
+                for (const type of fn.valueAbi ? [] : [...fn.params.map(p => p.type), fn.returns]) {
+                    if (!['int', 'c_int', 'float', 'bool', 'string', 'void'].includes(type.name) || type.args.length || type.nullable)
+                        this.report(type.span, `Type ${typeName(type)} is not supported at the C FFI boundary`, 'FFI');
+                }
             }
         }
         if (fn.name === 'drop' && (fn.params.length || fn.throws.length || fn.returns.name !== 'void' || fn.uses?.length))
             this.report(fn.span, 'drop must take no inputs, return void, and perform only local cleanup; external effects require an explicit method', 'EFFECT');
     }
+    checkNativeSignature(fn, file, binding) {
+        const check = (type, view, span) => {
+            const name = view.kind === 'i64' ? 'int' : view.kind === 'i32' ? 'c_int' : view.kind === 'f64' ? 'float' : view.kind === 'utf8' ? 'string' : view.kind === 'bytes' ? 'Bytes' : view.kind;
+            const valid = view.kind === 'resource' ? type.kind === 'resource' && this.native.resources.get(type.def.node)?.module + '.' + type.name === view.resource && this.native.providers.get(type.def.node) === this.native.providers.get(fn) :
+                view.kind === 'f64-list' || view.kind === 'utf8-list' ? type.name === 'List' && type.args.length === 1 && type.args[0].name === (view.kind === 'f64-list' ? 'float' : 'string') : type.name === name;
+            if (!valid || type.nullable || type.optional)
+                this.report(span, `Native contract expects ${view.resource ?? view.kind}, got ${tyName(type)}`, 'NATIVE_ABI');
+        };
+        if (fn.body || fn.typeParams.length || fn.params.some(p => p.injected) || fn.annotations?.length)
+            this.report(fn.span, 'Native ABI declarations have concrete inputs, no body, no resolve parameters, and no interceptors', 'NATIVE_ABI');
+        if (fn.params.length !== binding.params.length)
+            this.report(fn.span, 'Native parameter count differs from the binding descriptor', 'NATIVE_ABI');
+        fn.params.forEach((p, i) => {
+            const view = binding.params[i];
+            if (!view)
+                return;
+            if (p.name !== view.name)
+                this.report(p.span, 'Native parameter label differs from the binding descriptor: ' + view.name, 'NATIVE_ABI');
+            check(this.resolveType(p.type, file), view, p.span);
+            const ownership = view.kind === 'resource' ? view.ownership === 'consume' ? 'own' : view.ownership === 'borrow' ? 'borrow' : 'managed' : 'managed';
+            if (p.ownership !== ownership)
+                this.report(p.span, 'Native parameter ownership differs from its binding descriptor', 'NATIVE_ABI');
+        });
+        check(this.returnType(fn, file), binding.result, fn.returns.span);
+        if ((binding.result.kind === 'resource') !== (fn.returnOwnership === 'own'))
+            this.report(fn.span, 'Native result ownership differs from its binding descriptor', 'NATIVE_ABI');
+        const errors = fn.throws.map(t => this.resolveType(t, file));
+        if (errors.length !== (binding.error ? 1 : 0) || binding.error && errors[0]?.def?.id !== this.native.errors.get(fn)?.id)
+            this.report(fn.span, 'Native checked errors differ from the binding descriptor', 'NATIVE_ABI');
+        if (binding.error) {
+            const error = errors[0]?.def?.node;
+            if (error?.kind !== 'class' || error.typeParams.length || error.fields.length !== 2 || error.fields[0].name !== 'code' || error.fields[0].type.name !== 'int' || error.fields[1].name !== 'message' || error.fields[1].type.name !== 'string' || error.fields.some(p => p.injected || p.ownership !== 'managed' || p.type.nullable || p.type.optional || p.type.args.length) || initializationOf(error).length || error.annotations?.length)
+                this.report(fn.span, 'Native status errors require an Error class with int code and string message inputs and no constructor work', 'NATIVE_ABI');
+        }
+        const uses = (fn.uses ?? []).map(u => u.source + '.' + u.operation).sort(), changes = [...(fn.changes ?? [])].sort();
+        if (JSON.stringify(uses) !== JSON.stringify([...binding.uses].sort()) || JSON.stringify(changes) !== JSON.stringify([...binding.changes].sort()))
+            this.report(fn.span, 'Native effects or mutation differ from the binding descriptor', 'NATIVE_ABI');
+    }
     checkInterceptorShape(def) {
         const node = def.node;
         const types = this.paramsFor(node.typeParams, node, def.file);
@@ -763,6 +819,11 @@ class Checker {
         if (!cls.record && cls.implements.length === 0)
             this.report(cls.span, `${cls.name} must implement at least one interface`, 'INTERFACE');
         const params = this.paramsFor(cls.typeParams, cls, def.file);
+        for (const error of cls.validationErrors ?? []) {
+            const type = this.resolveType(error, def.file, params);
+            if (!this.implementsError(type))
+                this.report(error.span, `Thrown type ${typeName(error)} must implement Error`);
+        }
         this.checkVariance(cls, def.file);
         const names = new Set();
         for (const field of fieldsOf(cls)) {
@@ -770,6 +831,8 @@ class Checker {
                 this.report(field.span, `Duplicate field ${field.name}`);
             names.add(field.name);
             this.resolveType(field.type, def.file, params);
+            if (this.resolveType(field.type, def.file, params).kind === 'resource' && field.ownership !== 'own')
+                this.report(field.span, 'Native resource fields require own ownership', 'OWN');
             if (cls.record && (field.mutable || field.injected || field.ownership !== 'managed'))
                 this.report(field.span, 'Record fields are immutable data; dependencies and ownership belong in behavioral classes', 'RECORD');
             if (cls.record && !this.immutableData(this.resolveType(field.type, def.file, params)))
@@ -994,6 +1057,8 @@ class Checker {
                 continue;
             }
             const interfaceDef = this.project.scopes.get(item.span.file)?.get(item.key);
+            if (target.node.validationErrors?.length)
+                this.report(item.span, `${target.name} has a checked constructor failure; construct it explicitly and catch or propagate the error instead of binding it`, 'DI');
             let exposedType = targetType;
             if (interfaceDef?.node.kind === 'interface') {
                 exposedType = this.resolveType({ name: item.key, args: item.keyTypeArgs,
@@ -1554,6 +1619,8 @@ class Checker {
             const expected = stmt.declaredType ? this.resolveType(stmt.declaredType, context.file, context.types) :
                 stmt.target.kind === 'name' ? context.locals.get(stmt.target.name)?.declaredType ?? context.locals.get(stmt.target.name)?.type : undefined;
             const value = this.checkExpression(stmt.value, context, expected);
+            if (value.kind === 'resource' && stmt.target.kind === 'name' && stmt.ownership !== 'own' && context.locals.get(stmt.target.name)?.origin !== 'field')
+                this.report(stmt.span, 'Native resources must be held by own bindings', 'OWN');
             const source = stmt.value.kind === 'name' ? context.locals.get(stmt.value.name) : undefined;
             const origins = this.placesOf(stmt.value, context);
             const ownedSource = this.ownershipOf(stmt.value, context) === 'own';
@@ -1585,9 +1652,9 @@ class Checker {
                     context.flow.declare(stmt.target.name, origins, !!value.readonly, { source: sourceName(stmt.value) });
                 }
                 else if (existing) {
-                    if (existing.ownership === 'own')
+                    if (existing.ownership === 'own' && existing.origin !== 'field')
                         this.report(stmt.target.span, `Reassigning owned value ${stmt.target.name} is not supported; use a new scope`, 'OWN');
-                    if (source?.ownership === 'own')
+                    if (source?.ownership === 'own' && !(existing.origin === 'field' && existing.ownership === 'own'))
                         this.report(stmt.value.span, 'Cannot copy an owned value into a managed variable', 'OWN');
                     if (existing.origin === 'field' && existing.ownership !== 'own' &&
                         !context.initializing && !context.borrowed.has('self') && context.locals.get('self')?.ownership !== 'borrow')
@@ -1613,6 +1680,12 @@ class Checker {
                         existing.type = { ...declared, nullable: value.nullable, optional: value.optional, readonly: value.readonly, frozen: value.frozen };
                     context.flow.rebind(stmt.target.name, origins, !!value.readonly, stmt.span, (span, message) => this.report(span, message, 'BORROW'), sourceName(stmt.value));
                     existing.moved = false;
+                    if (existing.origin === 'field' && existing.ownership === 'own') {
+                        if (source?.ownership === 'own' && stmt.value.kind === 'name')
+                            this.moveOwnedLocal(stmt.value.name, stmt.value.span, context);
+                        else if (!['own', 'fresh'].includes(this.ownershipOf(stmt.value, context)))
+                            this.report(stmt.value.span, 'An owned field requires a new object or another owned value', 'OWN');
+                    }
                 }
                 else {
                     if (source?.ownership === 'own')
@@ -1638,6 +1711,8 @@ class Checker {
                 const node = object.def?.node;
                 const fieldName = stmt.target.name;
                 const field = node?.kind === 'class' || node?.kind === 'interceptor' ? fieldsOf(node).find(item => item.name === fieldName) : undefined;
+                if (value.kind === 'resource' && field?.ownership !== 'own')
+                    this.report(stmt.span, 'Native resources must be held by own fields', 'OWN');
                 if (!(context.initializing && root === 'self') && !field?.mutable)
                     this.report(stmt.target.span, `Field ${fieldName} is read-only; declare mutable storage`, 'MUTABILITY');
                 if (object.readonly && !(context.initializing && root === 'self'))
@@ -1986,21 +2061,22 @@ class Checker {
         if (visiting.has(node))
             return false;
         visiting.add(node);
-        const result = (this.interceptorPlans.get(node) ?? []).every(layer => {
-            const interceptor = layer.definition.node;
-            return returnsFresh(layer.around.body ?? [], new Set(interceptor.fields.map(field => field.name)), expr => {
-                if (expr.kind !== 'call' || expr.callee.kind !== 'name')
-                    return false;
-                if (expr.callee.name === 'next')
-                    return true;
-                const def = this.project.scopes.get(layer.definition.file)?.get(expr.callee.name);
-                return def?.node.kind === 'class' && this.constructorIsFresh(def.node, visiting);
-            });
-        });
+        const result = (this.interceptorPlans.get(node) ?? []).every(layer => this.layerReturnsFresh(layer, visiting));
         visiting.delete(node);
         this.constructorFreshness.set(node, result);
         return result;
     }
+    layerReturnsFresh(layer, visiting = new Set()) {
+        const interceptor = layer.definition.node;
+        return returnsFresh(layer.around.body ?? [], new Set(interceptor.fields.map(field => field.name)), expr => {
+            if (expr.kind !== 'call' || expr.callee.kind !== 'name')
+                return false;
+            if (expr.callee.name === 'next')
+                return true;
+            const def = this.project.scopes.get(layer.definition.file)?.get(expr.callee.name);
+            return def?.node.kind === 'class' && this.constructorIsFresh(def.node, visiting);
+        });
+    }
     checkAllowedError(type, span, context) {
         if (context.deferredErrors) {
             context.deferredErrors.push(type);
@@ -2146,6 +2222,8 @@ class Checker {
             type = { ...builtin('Task'), args: [result] };
             if (expr.call.kind === 'call' && context.scope) {
                 const plan = this.callPlans.get(expr.call), task = [...allocationOrigin(expr.span)][0], scope = `tasks:${context.scope.file}:${context.scope.start}`;
+                if (plan?.returnOwnership === 'own')
+                    this.report(expr.call.span, 'A task cannot return an owned value. Return immutable data, or create and release the owned resource inside the task.', 'CONCURRENCY');
                 context.flow.registerTask(task, scope, errors);
                 const captureOrigins = (origins, actual, exclusive, span) => {
                     if (!this.isReference(actual))
@@ -2299,6 +2377,9 @@ class Checker {
         }
         else if (expr.kind === 'call') {
             type = this.checkCall(expr, context);
+            const plan = this.callPlans.get(expr);
+            if (plan)
+                plan.returnOwnership = this.ownershipOf(expr, context) === 'own' ? 'own' : 'managed';
         }
         this.expressionTypes.set(expr, type);
         this.expressionOrigins.set(expr, this.placesOf(expr, context));
@@ -2611,6 +2692,7 @@ class Checker {
         }
         if (expr.callee.kind === 'name' && expr.callee.name === 'Shared') {
             const plan = this.planCall(expr, ['value'], 'Shared'), index = plan.sourceIndices[0];
+            plan.ownerships = ['own'];
             const result = index === undefined ? errorTy : argTypes[index];
             if (index !== undefined && !['fresh', 'own'].includes(this.ownershipOf(expr.args[index], context)))
                 this.report(expr.args[index].span, 'Shared takes a fresh value or an owned value; existing mutable aliases cannot survive the transfer', 'OWN');
@@ -2915,7 +2997,7 @@ class Checker {
         }
         if (fn.externC && !context.unsafe)
             this.report(expr.span, `Call to extern C function ${fn.name} requires unsafe { ... }`, 'FFI');
-        if (fn.externC && !fn.nativePure && !(fn.valueAbi && fn.uses?.length)) {
+        if (fn.externC && !fn.nativePure && !this.native.functions.has(fn) && !(fn.valueAbi && fn.uses?.length)) {
             const native = this.project.scopes.get(fnFile)?.get(fn.name);
             this.requireUse(`C:${native?.id ?? fn.name}`, `C.${fn.name}`, expr.span, context);
         }
@@ -3053,7 +3135,7 @@ class Checker {
             else if (!['own', 'fresh'].includes(this.ownershipOf(argument, context)))
                 this.report(argument.span, 'Owned field requires a new object or owned argument', 'OWN');
         }
-        else if (this.ownershipOf(argument, context) === 'own' && param.ownership !== 'borrow')
+        else if (this.ownershipOf(argument, context) === 'own' && param.ownership !== 'borrow' && this.expressionTypes.get(argument)?.kind !== 'resource')
             this.report(argument.span, 'Cannot copy an owned value into managed storage', 'OWN');
         if (param.ownership === 'borrow') {
             if (context.flow.hasTaskCapture(this.placesOf(argument, context)))

package/src/cli.js

@@ -4,6 +4,13 @@ import { spawnSync } from 'node:child_process';
 import { typeName } from "./ast.js";
 import { checkProject } from "./checker.js";
 import { generateC } from "./codegen.js";
+import { generateLLVM } from "./llvm.js";
+import { lowerToIR, BackendUnsupported } from "./ir.js";
+import { IRVerificationError } from "./ir-verify.js";
+import { compileLLVM } from "./llvm-native.js";
+import { prepareNativePackages } from "./native-artifacts.js";
+import { prepareLLVMCompiler } from "./compiler-packs.js";
+import { bindNativeHeader } from "./native-bindings.js";
 import { diagnosticHelp } from "./help.js";
 import { loadProject } from "./project.js";
 import { definitionAt } from "./navigation.js";
@@ -55,9 +62,10 @@ function printDiagnostics(diagnostics, json, root) {
 }
 function usage() {
     process.stdout.write(`AugScript compiler\n\n` +
-        `Usage: aug <init|check|build|run|emit-c|test|openapi|format|migrate|spec|bench|explain|context|lsp|symbols|definition|complete|hover|fixes|semantic-tokens> [project directory] [options] [-- args]\n` +
+        `Usage: aug <init|check|build|run|emit-c|emit-llvm|emit-ir|test|openapi|format|migrate|spec|bench|explain|context|lsp|symbols|definition|complete|hover|fixes|semantic-tokens> [project directory] [options] [-- args]\n` +
         `New application: aug init DIRECTORY [--template hello|weather]\n` +
         `Run: aug run [project directory] [--offline] [-- args] — prepare dependencies, compile, and start\n` +
+        `Backend: LLVM is the default on macOS 14+ ARM64 and GNU/Linux x64/ARM64 with glibc 2.36+. August installs its compiler pack; no separate native toolchain is needed. --backend c selects the migration reference.\n` +
         `Tests: aug test [project directory] [GROUP_NAME] [--group GROUP_NAME] [--list] [--coverage] [--json] [--timeout milliseconds]\n` +
         `Format: aug format [project directory] [--file path] [--write]\n` +
         `Specifications: aug spec [project directory] [--check] [--json]\n` +
@@ -66,6 +74,7 @@ function usage() {
         `Benchmark: aug bench [project directory] [--iterations 10] [--warmup 2] [--json] [-- args]\n` +
         `Packages: aug package init DIRECTORY --name @owner/name; aug package pack DIRECTORY\n` +
         `Dependencies: aug add URL --as NAME [--project DIRECTORY]; aug install [project directory] [--frozen|--update] [--offline]\n` +
+        `Native maintainers: aug bind header HEADER --contract native.abi.json --target TRIPLE --output DIRECTORY --clang PATH [-- CLANG_FLAGS]\n` +
         `Entry point: main.aug at the project root.\n`);
 }
 export async function main(argv) {
@@ -80,6 +89,34 @@ export async function main(argv) {
         usage();
         return 0;
     }
+    if (command === 'bind') {
+        const boundary = argv.indexOf('--'), arguments_ = boundary < 0 ? argv : argv.slice(0, boundary), values = {};
+        if (arguments_[1] !== 'header' || !arguments_[2] || arguments_[2].startsWith('--')) {
+            process.stderr.write('Use aug bind header HEADER --contract FILE --target TRIPLE --output DIRECTORY --clang PATH\n');
+            return 2;
+        }
+        for (let index = 3; index < arguments_.length; index++) {
+            const flag = arguments_[index];
+            if (!['--contract', '--target', '--output', '--clang'].includes(flag) || values[flag] !== undefined || !arguments_[index + 1] || arguments_[index + 1].startsWith('--')) {
+                process.stderr.write('Invalid or duplicate native binding option: ' + flag + '\n');
+                return 2;
+            }
+            values[flag] = arguments_[++index];
+        }
+        if (['--contract', '--target', '--output', '--clang'].some(flag => !values[flag])) {
+            process.stderr.write('Native header validation requires --contract, --target, --output and --clang. No tool is installed automatically.\n');
+            return 2;
+        }
+        try {
+            bindNativeHeader({ header: arguments_[2], contract: values['--contract'], target: values['--target'], output: values['--output'], clang: values['--clang'], flags: boundary < 0 ? [] : argv.slice(boundary + 1) });
+            process.stdout.write('Checked native declarations written to ' + resolve(values['--output']) + '\n');
+            return 0;
+        }
+        catch (error) {
+            process.stderr.write(failureMessage(error) + '\n');
+            return 1;
+        }
+    }
     if (command === 'add') {
         const aliasIndex = argv.indexOf('--as'), projectIndex = argv.indexOf('--project');
         if (!argv[1] || argv[1].startsWith('--') || aliasIndex < 0 || !argv[aliasIndex + 1]) {
@@ -99,6 +136,7 @@ export async function main(argv) {
         try {
             const alias = argv[aliasIndex + 1], root = resolve(projectIndex < 0 ? process.cwd() : argv[projectIndex + 1]);
             const lock = addPackage(root, argv[1], alias, argv.includes('--offline'));
+            await prepareNativePackages(root, { offline: argv.includes('--offline') });
             process.stdout.write(`Added ${alias}; installed ${lock.packages.length} source package(s).\nImport public names with: import NAME from ${alias}\n`);
             return 0;
         }
@@ -129,6 +167,7 @@ export async function main(argv) {
                 ? (command === 'install' ? argv[1] : argv[2]) : process.cwd());
             if (command === 'install') {
                 const lock = installPackages(root, argv.includes('--frozen'), argv.includes('--offline'), argv.includes('--update'));
+                await prepareNativePackages(root, { offline: argv.includes('--offline'), frozen: argv.includes('--frozen') });
                 process.stdout.write(`Installed ${lock.packages.length} August package(s); aug.lock.json is current.\n`);
             }
             else if (argv[1] === 'init') {
@@ -163,7 +202,7 @@ export async function main(argv) {
     }
     if (command === 'lsp')
         return runLanguageServer(resolve(argv[1] ?? process.cwd()));
-    if (!['check', 'build', 'run', 'emit-c', 'test', 'openapi', 'format', 'migrate', 'spec', 'bench', 'explain', 'context', 'symbols', 'definition',
+    if (!['check', 'build', 'run', 'emit-c', 'emit-llvm', 'emit-ir', 'test', 'openapi', 'format', 'migrate', 'spec', 'bench', 'explain', 'context', 'symbols', 'definition',
         'complete', 'hover', 'fixes', 'semantic-tokens'].includes(command)) {
         process.stderr.write(`Unknown command ${command}\n`);
         usage();
@@ -176,8 +215,8 @@ export async function main(argv) {
         usage();
         return 0;
     }
-    const valueOptions = new Set(['--out', '--stdin-file', '--file', '--name', '--offset', '--budget', '--baseline', '--group', '--case', '--timeout', '--iterations', '--warmup']);
-    const booleanOptions = new Set(['--json', '--coverage', '--list', '--write', '--check', '--offline']);
+    const valueOptions = new Set(['--backend', '--out', '--stdin-file', '--file', '--name', '--offset', '--budget', '--baseline', '--group', '--case', '--timeout', '--iterations', '--warmup']);
+    const booleanOptions = new Set(['--json', '--coverage', '--list', '--write', '--check', '--offline', '--frozen']);
     for (let index = 0; index < options.length; index++) {
         const option = options[index];
         if (valueOptions.has(option)) {
@@ -193,6 +232,12 @@ export async function main(argv) {
         }
     }
     const json = options.includes('--json');
+    const backendIndex = options.indexOf('--backend');
+    let backend = backendIndex < 0 ? 'llvm' : options[backendIndex + 1];
+    if (!['c', 'llvm'].includes(backend)) {
+        process.stderr.write('--backend must be c or llvm\n');
+        return 2;
+    }
     const outIndex = options.indexOf('--out');
     const outputOption = outIndex >= 0 ? options[outIndex + 1] : undefined;
     const stdinIndex = options.indexOf('--stdin-file');
@@ -217,6 +262,7 @@ export async function main(argv) {
     const iterations = iterationsIndex >= 0 ? Number(options[iterationsIndex + 1]) : 10;
     const warmup = warmupIndex >= 0 ? Number(options[warmupIndex + 1]) : 2;
     const positionals = options.filter((arg, i) => !arg.startsWith('--') &&
+        (backendIndex < 0 || i !== backendIndex + 1) &&
         (outIndex < 0 || i !== outIndex + 1) &&
         (stdinIndex < 0 || i !== stdinIndex + 1) &&
         (fileIndex < 0 || i !== fileIndex + 1) &&
@@ -250,8 +296,10 @@ export async function main(argv) {
         if (!existsSync(root) || !statSync(root).isDirectory())
             throw new Error(`Project directory does not exist: ${root}\nUse aug init DIRECTORY to create a project, or run aug run from the folder containing main.aug.`);
         if (command === 'run')
-            prepareRunPackages(root, options.includes('--offline'));
+            prepareRunPackages(root, options.includes('--offline'), options.includes('--frozen'));
         const project = loadProject(root, overrides);
+        if (backendIndex < 0)
+            backend = project.config.backend ?? 'llvm';
         if (project.library && ['build', 'run', 'bench', 'openapi'].includes(command))
             throw new Error('This is an August library; use check, test, or package pack. Import its exports from an application with main.aug to run it.');
         if (command === 'format' || command === 'migrate') {
@@ -296,10 +344,17 @@ export async function main(argv) {
             }
             const results = [];
             const coverage = options.includes('--coverage'), reports = [];
+            const nativeInputs = backend === 'llvm' ? await prepareNativePackages(root, { offline: options.includes('--offline'), frozen: options.includes('--frozen') }) : undefined;
+            const toolchain = backend === 'llvm' ? await prepareLLVMCompiler(options.includes('--offline'), { root, frozen: options.includes('--frozen') }) : undefined;
             for (const [index, { unit, checked: testChecked }] of checks.entries()) {
-                const generated = generateC(testChecked, { coverage });
-                await prepareNativeDependencies(generated, { offline: options.includes('--offline') });
-                const native = compileNative(root, generated, { testIndex: index, checked: testChecked });
+                let native;
+                if (backend === 'llvm')
+                    native = compileLLVM(testChecked, { testIndex: index, coverage, native: nativeInputs, toolchain });
+                else {
+                    const generated = generateC(testChecked, { coverage });
+                    await prepareNativeDependencies(generated, { offline: options.includes('--offline') });
+                    native = compileNative(root, generated, { testIndex: index, checked: testChecked });
+                }
                 const report = join(root, '.aug-build', 'tests', `coverage-${index}.tsv`);
                 reports.push(report);
                 if (coverage)
@@ -387,23 +442,41 @@ export async function main(argv) {
             process.stdout.write(json ? JSON.stringify(result) + '\n' : result.stale.length ? 'Stale specifications:\n' + result.stale.map(file => '  ' + file).join('\n') + '\n' : `${result.files} specification artifact(s) ${options.includes('--check') ? 'are current' : 'generated'}.\n`);
             return result.stale.length ? 1 : 0;
         }
-        if (['build', 'run', 'bench'].includes(command)) {
+        if (['build', 'run', 'bench'].includes(command) && !options.includes('--frozen')) {
             checked = updateSpecHints(checked);
             if (checked.diagnostics.some(issue => issue.severity !== 'warning')) {
                 printDiagnostics(checked.diagnostics, json, root);
                 return 1;
             }
         }
-        const generated = generateC(checked);
+        if (command === 'emit-llvm') {
+            process.stdout.write(generateLLVM(lowerToIR(checked)));
+            return 0;
+        }
+        if (command === 'emit-ir') {
+            process.stdout.write(JSON.stringify(lowerToIR(checked), null, 2) + '\n');
+            return 0;
+        }
+        if ((backend === 'c' || command === 'emit-c') && checked.native.resources.size + checked.native.functions.size)
+            throw new Error('NATIVE_BACKEND: Checked native packages require --backend llvm. The C reference backend cannot lower this native ABI.');
         if (command === 'emit-c') {
-            process.stdout.write(generated);
+            process.stdout.write(generateC(checked));
             return 0;
         }
         if (command === 'bench' && (!Number.isInteger(iterations) || iterations < 1 || iterations > 1000 ||
             !Number.isInteger(warmup) || warmup < 0 || warmup > 100 || !Number.isInteger(timeout) || timeout < 1))
             throw new Error('bench requires iterations 1–1000, warmup 0–100, and a positive timeout');
-        await prepareNativeDependencies(generated, { offline: options.includes('--offline') });
-        const native = compileNative(root, generated, { output: outputOption, release: command === 'bench' ? true : undefined, checked });
+        let native;
+        if (backend === 'llvm') {
+            const inputs = await prepareNativePackages(root, { offline: options.includes('--offline'), frozen: options.includes('--frozen') });
+            const toolchain = await prepareLLVMCompiler(options.includes('--offline'), { root, frozen: options.includes('--frozen') });
+            native = compileLLVM(checked, { output: outputOption, release: command === 'bench' || project.config.optimization === 'release', native: inputs, toolchain });
+        }
+        else {
+            const generated = generateC(checked);
+            await prepareNativeDependencies(generated, { offline: options.includes('--offline') });
+            native = compileNative(root, generated, { output: outputOption, release: command === 'bench' ? true : undefined, checked });
+        }
         const output = native.output;
         if (native.status !== 0) {
             if (native.diagnostics.length)
@@ -412,7 +485,8 @@ export async function main(argv) {
                 process.stderr.write(native.error + '\n');
             return native.status;
         }
-        updateSpecs(checked);
+        if (!options.includes('--frozen'))
+            updateSpecs(checked);
         if (command === 'build') {
             process.stdout.write(json ? JSON.stringify({ output, sourceMap: output + '.augmap.json' }) + '\n' : `${output}\n`);
             return 0;
@@ -432,6 +506,10 @@ export async function main(argv) {
         return run.status ?? 1;
     }
     catch (error) {
+        if (error instanceof BackendUnsupported || error instanceof IRVerificationError) {
+            printDiagnostics([{ ...error.span, code: error.code, message: error.message }], json, root);
+            return 1;
+        }
         process.stderr.write(failureMessage(error) + '\n');
         return error instanceof Error && 'exitCode' in error && typeof error.exitCode === 'number' ? error.exitCode : 1;
     }