@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/src/native-contracts.js

@@ -0,0 +1,295 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, realpathSync } from 'node:fs';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { release } from 'node:os';
+/** The public native ABI never exposes August runtime layouts. */
+export const nativeProfile = 'aug-native-abi-1';
+const digest = /^[0-9a-f]{64}$/;
+const identifier = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const moduleName = /^[A-Za-z][A-Za-z0-9_]*(?:\/[A-Za-z][A-Za-z0-9_]*)*$/;
+const fail = (message) => { throw new Error('NATIVE_ABI: ' + message); };
+const object = (value, label) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        fail(label + ' must be an object');
+    return value;
+};
+const fields = (value, allowed, label) => {
+    for (const key of Object.keys(value))
+        if (!allowed.includes(key))
+            fail(`${label} contains unsupported field ${key}`);
+};
+const string = (value, label) => {
+    if (typeof value !== 'string' || !value || value.includes('\0'))
+        fail(label + ' must be a nonempty string');
+    return value;
+};
+const array = (value, label) => {
+    if (!Array.isArray(value) || value.length > 10000)
+        fail(label + ' must be an array of at most 10,000 entries');
+    return value;
+};
+const strings = (value, label) => array(value, label).map(item => string(item, label));
+const positive = (value, label) => { if (!Number.isSafeInteger(value) || Number(value) <= 0)
+    fail(label + ' must be a positive safe integer'); };
+const hash = (value, label) => { if (typeof value !== 'string' || !digest.test(value))
+    fail(label + ' must be a lowercase SHA-256 digest'); };
+const symbol = (value, label) => { if (typeof value !== 'string' || !identifier.test(value))
+    fail(label + ' must be a C identifier'); };
+const https = (value, label) => {
+    let url;
+    try {
+        url = new URL(string(value, label));
+    }
+    catch {
+        fail(label + ' must be an HTTPS URL');
+    }
+    if (url.protocol !== 'https:' || url.username || url.password || url.hash)
+        fail(label + ' must be an HTTPS URL without credentials or a fragment');
+};
+/** Artifact paths are portable and cannot name a file outside their archive. */
+export function nativePath(value) {
+    const path = string(value, 'relative artifact path');
+    if (isAbsolute(path) || path.includes('\\') || path.split('/').some(part => !part || part === '.' || part === '..' || part.startsWith('.')) || /[:\r\n]/.test(path))
+        fail('Expected a relative artifact path without traversal: ' + path);
+    return path;
+}
+/** Source installation validates metadata; it does not run a native build recipe. */
+export function validateNativeManifest(value) {
+    const native = object(value, 'native metadata');
+    fields(native, ['profile', 'bindings', 'bindingsSha256', 'upstream', 'artifacts', 'sourceBuild'], 'native metadata');
+    if (native.profile !== nativeProfile)
+        fail('Unsupported native profile ' + native.profile);
+    nativePath(native.bindings);
+    if (native.bindings !== 'native.abi.json')
+        fail('Bindings must be declared in native.abi.json at the package root');
+    hash(native.bindingsSha256, 'bindingsSha256');
+    const upstream = object(native.upstream, 'upstream');
+    fields(upstream, ['repository', 'version', 'sourceRevision'], 'upstream');
+    https(upstream.repository, 'upstream.repository');
+    string(upstream.version, 'upstream.version');
+    if (!/^[0-9a-f]{40,64}$/.test(upstream.sourceRevision ?? ''))
+        fail('upstream.sourceRevision must pin a full source revision or archive digest');
+    const artifacts = array(native.artifacts, 'artifacts');
+    if (!artifacts.length)
+        fail('At least one prebuilt artifact is required');
+    const ids = new Set(), selections = new Set();
+    for (const entry of artifacts) {
+        const artifact = object(entry, 'artifact');
+        fields(artifact, ['id', 'target', 'url', 'sha256', 'maximumDownloadBytes', 'maximumUnpackedBytes', 'link', 'runtime', 'components', 'fileManifest', 'provenance', 'notices'], 'artifact');
+        string(artifact.id, 'artifact.id');
+        if (ids.has(artifact.id))
+            fail('Duplicate artifact id ' + artifact.id);
+        ids.add(artifact.id);
+        const target = object(artifact.target, 'artifact.target');
+        fields(target, ['triple', 'os', 'arch', 'minimumOS', 'minimumLibc', 'cpuBaseline', 'libc', 'cxxRuntime', 'cxxABI', 'features'], 'artifact.target');
+        const expected = nativeTarget(string(target.triple, 'target.triple'));
+        if (expected.os !== target.os || expected.arch !== target.arch || expected.libc !== target.libc)
+            fail('Target triple does not match its OS, architecture, or libc');
+        string(target.cpuBaseline, 'target.cpuBaseline');
+        if (target.os === 'macos' && (!/^\d+\.\d+(?:\.\d+)?$/.test(target.minimumOS ?? '')))
+            fail('macOS artifacts declare minimumOS');
+        if (target.os === 'linux' && target.libc === 'glibc' && !/^\d+\.\d+(?:\.\d+)?$/.test(target.minimumLibc ?? ''))
+            fail('GNU/Linux artifacts declare minimumLibc');
+        if (target.minimumLibc !== undefined && (target.os !== 'linux' || target.libc !== 'glibc'))
+            fail('minimumLibc belongs to GNU/Linux artifacts');
+        for (const key of ['cxxRuntime', 'cxxABI'])
+            if (target[key] !== undefined)
+                string(target[key], key);
+        if (target.features !== undefined)
+            strings(target.features, 'target.features');
+        const selection = JSON.stringify([target.triple, target.minimumOS ?? '', target.minimumLibc ?? '', target.features ?? []]);
+        if (selections.has(selection))
+            fail('Ambiguous artifact selection for ' + target.triple);
+        selections.add(selection);
+        https(artifact.url, 'artifact.url');
+        hash(artifact.sha256, 'artifact.sha256');
+        positive(artifact.maximumDownloadBytes, 'maximumDownloadBytes');
+        positive(artifact.maximumUnpackedBytes, 'maximumUnpackedBytes');
+        const link = object(artifact.link, 'link');
+        fields(link, ['kind', 'libraries'], 'link');
+        if (!['dynamic', 'static'].includes(link.kind))
+            fail('link.kind must be dynamic or static');
+        if (!array(link.libraries, 'link.libraries').length)
+            fail('An artifact must supply link libraries');
+        link.libraries.forEach(nativePath);
+        const runtime = object(artifact.runtime, 'runtime');
+        fields(runtime, ['files', 'relocation', 'closureManifest'], 'runtime');
+        array(runtime.files, 'runtime.files').forEach(nativePath);
+        if (runtime.relocation !== 'loader-relative')
+            fail('Runtime libraries must use loader-relative relocation');
+        if (runtime.closureManifest !== undefined)
+            nativePath(runtime.closureManifest);
+        for (const component of array(artifact.components, 'components')) {
+            const c = object(component, 'component');
+            fields(c, ['id', 'version', 'compatibilityKey', 'linkage', 'required'], 'component');
+            for (const key of ['id', 'version', 'compatibilityKey'])
+                string(c[key], key);
+            if (!['static', 'dynamic'].includes(c.linkage) || typeof c.required !== 'boolean')
+                fail('Invalid component linkage/required');
+        }
+        for (const key of ['fileManifest', 'provenance', 'notices'])
+            nativePath(artifact[key]);
+    }
+    if (native.sourceBuild !== undefined) {
+        const build = object(native.sourceBuild, 'sourceBuild');
+        fields(build, ['recipe', 'inputs', 'tools', 'automatic'], 'sourceBuild');
+        nativePath(build.recipe);
+        nativePath(build.inputs);
+        strings(build.tools, 'sourceBuild.tools');
+        if (build.automatic !== false)
+            fail('Native source builds must be explicitly requested; automatic must be false');
+    }
+    return native;
+}
+function view(value, result) {
+    const v = object(value, 'native view');
+    fields(v, ['kind', 'resource', 'ownership', 'release', 'releaseLength', 'minimum', 'maximum', ...(result ? [] : ['name'])], 'native view');
+    if (!['void', 'i64', 'i32', 'f64', 'bool', 'utf8', 'bytes', 'f64-list', 'utf8-list', 'resource'].includes(v.kind))
+        fail('Unsupported native kind ' + v.kind);
+    if (v.kind === 'void' && !result)
+        fail('void is only a result');
+    if (v.kind === 'resource') {
+        string(v.resource, 'resource identity');
+        if (!result && !['read', 'borrow', 'consume'].includes(v.ownership))
+            fail('A resource input requires read, borrow, or consume ownership');
+        if (result && v.ownership !== undefined)
+            fail('Resource results always transfer ownership; do not declare an input loan');
+    }
+    else if (v.resource !== undefined || v.ownership !== undefined)
+        fail('Resource ownership is only valid on resources');
+    if (result && ['utf8', 'bytes', 'f64-list', 'utf8-list'].includes(v.kind) && !v.release)
+        fail('Allocated native results require a matching release symbol');
+    if (result && v.kind === 'utf8-list')
+        fail('utf8-list outputs are not in this ABI profile');
+    if (v.release !== undefined)
+        symbol(v.release, 'result.release');
+    if ((v.release !== undefined || v.releaseLength !== undefined) && (!result || !['utf8', 'bytes', 'f64-list'].includes(v.kind)))
+        fail('Release metadata belongs only to allocated buffer results');
+    if (v.releaseLength !== undefined && typeof v.releaseLength !== 'boolean')
+        fail('releaseLength must be boolean');
+    if ((v.minimum !== undefined || v.maximum !== undefined) && !['i64', 'i32'].includes(v.kind))
+        fail('Integer bounds require i64 or i32');
+    for (const key of ['minimum', 'maximum'])
+        if (v[key] !== undefined && !Number.isSafeInteger(v[key]))
+            fail(key + ' must be a safe integer');
+    if (v.minimum !== undefined && v.maximum !== undefined && v.minimum > v.maximum)
+        fail('Empty native integer range');
+    return v;
+}
+export function validateNativeDescriptor(value) {
+    const descriptor = object(value, 'binding descriptor');
+    fields(descriptor, ['format', 'profile', 'resources', 'functions'], 'binding descriptor');
+    if (descriptor.format !== 1 || descriptor.profile !== nativeProfile)
+        fail('Unsupported binding descriptor version/profile');
+    const ids = new Set();
+    for (const entry of array(descriptor.resources, 'resources')) {
+        const r = object(entry, 'resource');
+        fields(r, ['module', 'name', 'release'], 'resource');
+        if (!moduleName.test(r.module ?? ''))
+            fail('Resource module must be a source-relative module path');
+        symbol(r.name, 'resource.name');
+        symbol(r.release, 'resource.release');
+        const id = r.module + '.' + r.name;
+        if (ids.has(id))
+            fail('Duplicate native resource ' + id);
+        ids.add(id);
+    }
+    const resources = new Set(ids);
+    ids.clear();
+    for (const entry of array(descriptor.functions, 'functions')) {
+        const fn = object(entry, 'function');
+        fields(fn, ['module', 'name', 'symbol', 'params', 'result', 'error', 'callingConvention', 'status', 'uses', 'changes', 'thread', 'retainsInputs'], 'function');
+        if (!moduleName.test(fn.module ?? ''))
+            fail('Function module must be a source-relative module path');
+        symbol(fn.name, 'function.name');
+        symbol(fn.symbol, 'function.symbol');
+        const id = fn.module + '.' + fn.name;
+        if (ids.has(id))
+            fail('Duplicate native function ' + id);
+        ids.add(id);
+        const names = new Set();
+        for (const p of array(fn.params, 'function.params')) {
+            view(p, false);
+            if (p.kind === 'resource' && !resources.has(p.resource))
+                fail('Unknown resource identity ' + p.resource);
+            symbol(p.name, 'parameter.name');
+            if (names.has(p.name))
+                fail('Duplicate parameter ' + p.name);
+            names.add(p.name);
+        }
+        const result = view(fn.result, true);
+        if (result.kind === 'resource' && !resources.has(result.resource))
+            fail('Unknown result resource identity ' + result.resource);
+        if (fn.callingConvention !== 'C' || !['i32', 'direct'].includes(fn.status) || fn.thread !== 'caller' || fn.retainsInputs !== false)
+            fail('Only C calls on the caller thread with call-duration loans are supported');
+        if (fn.error !== undefined) {
+            string(fn.error, 'function.error');
+            const dot = fn.error.lastIndexOf('.');
+            if (!moduleName.test(fn.error.slice(0, dot)) || !identifier.test(fn.error.slice(dot + 1)))
+                fail('Native checked errors require a module-qualified declaration identity');
+        }
+        if (fn.status === 'i32' && !fn.error)
+            fail('Status-returning native calls require a checked error type');
+        if (fn.status === 'direct' && (fn.error || result.kind === 'resource' || ['utf8', 'bytes', 'f64-list', 'utf8-list'].includes(result.kind)))
+            fail('Direct native calls support scalar results only');
+        strings(fn.uses, 'function.uses');
+        strings(fn.changes, 'function.changes');
+    }
+    return descriptor;
+}
+export function readNativeDescriptor(directory, native) {
+    const root = realpathSync(directory), file = realpathSync(resolve(root, native.bindings));
+    if (relative(root, file).split(sep).includes('..'))
+        fail('Binding descriptor escapes its package');
+    const bytes = readFileSync(file);
+    if (createHash('sha256').update(bytes).digest('hex') !== native.bindingsSha256)
+        throw new Error('NATIVE_INTEGRITY: binding descriptor differs from bindingsSha256 in ' + directory);
+    return validateNativeDescriptor(JSON.parse(bytes.toString('utf8')));
+}
+/** A target is a deployment identity, not an assumption that the host can build it. */
+export function nativeTarget(triple, minimumOS) {
+    triple ??= process.platform === 'darwin' ? (process.arch === 'arm64' ? 'aarch64' : 'x86_64') + '-apple-darwin' : process.platform === 'linux' ? (process.arch === 'arm64' ? 'aarch64' : 'x86_64') + '-unknown-linux-gnu' : (process.arch === 'arm64' ? 'aarch64' : 'x86_64') + '-pc-windows-msvc';
+    const match = /^(aarch64|x86_64)-(apple-darwin|unknown-linux-(gnu|musl)|pc-windows-msvc)$/.exec(triple);
+    if (!match)
+        throw new Error('NATIVE_TARGET: Unsupported target ' + triple);
+    const os = match[2] === 'apple-darwin' ? 'macos' : match[2].startsWith('unknown-linux') ? 'linux' : 'windows';
+    const arch = match[1] === 'aarch64' ? 'arm64' : 'x64';
+    return { triple, os, arch, cpuBaseline: arch === 'arm64' ? 'armv8-a' : 'x86-64', libc: os === 'macos' ? 'libSystem' : os === 'windows' ? 'ucrt' : match[3] === 'musl' ? 'musl' : 'glibc', ...(os === 'macos' ? { minimumOS: minimumOS ?? '14.0' } : {}) };
+}
+export function nativeHostTarget() {
+    // Darwin 23/24 are macOS 14/15. Apple's 2025 numbering change maps Darwin 25 to macOS 26.
+    const darwin = Number(release().split('.')[0]), macos = darwin >= 25 ? darwin + 1 : darwin - 9;
+    const target = nativeTarget(undefined, process.platform === 'darwin' ? `${macos}.0` : undefined);
+    if (process.platform === 'linux') {
+        const header = process.report.getReport()?.header;
+        if (header?.glibcVersionRuntime)
+            target.minimumLibc = header.glibcVersionRuntime;
+        else {
+            target.libc = 'musl';
+            target.triple = target.triple.replace(/-gnu$/, '-musl');
+        }
+    }
+    return target;
+}
+const versionAtLeast = (actual, required) => {
+    const a = actual.split('.').map(Number), b = required.split('.').map(Number);
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        if ((a[i] ?? 0) !== (b[i] ?? 0))
+            return (a[i] ?? 0) > (b[i] ?? 0);
+    }
+    return true;
+};
+export function selectNativeArtifact(artifacts, target) {
+    const matching = artifacts.filter(a => a.target.triple === target.triple && a.target.libc === target.libc &&
+        a.target.cpuBaseline === target.cpuBaseline && (!a.target.cxxRuntime ||
+        a.target.os === 'macos' && a.target.cxxRuntime === 'system-libc++' && a.target.cxxABI === 'apple-libc++' ||
+        a.target.os === 'linux' && a.target.cxxRuntime === 'bundled-libstdc++' && a.target.cxxABI === 'itanium-cxx11') &&
+        (!a.target.minimumLibc || !!target.minimumLibc && versionAtLeast(target.minimumLibc, a.target.minimumLibc)) &&
+        (!a.target.minimumOS || !!target.minimumOS && versionAtLeast(target.minimumOS, a.target.minimumOS)));
+    if (matching.length !== 1) {
+        const floors = artifacts.filter(a => a.target.triple === target.triple).map(a => a.target.minimumOS ?? a.target.minimumLibc).filter(Boolean);
+        const runtime = target.os === 'linux' ? 'glibc' : 'macOS', actual = target.os === 'linux' ? target.minimumLibc : target.minimumOS;
+        throw new Error('NATIVE_TARGET: ' + (matching.length ? 'Ambiguous prebuilt artifacts' : floors.length ? `This package requires ${runtime} ${floors.join(' or ')}+ and its declared C++ ABI; requested ${actual ?? 'unknown'}.` : 'No compatible prebuilt artifact for ' + target.triple) + ` Supported artifacts: ${artifacts.map(a => a.id + ' (' + a.target.triple + ')').join(', ')}. No source build was started.`);
+    }
+    return matching[0];
+}

package/src/native-declarations.js

@@ -0,0 +1,68 @@
+import { resolve } from 'node:path';
+import { readNativeDescriptor } from "./native-contracts.js";
+/** Resolve descriptors against exact source declarations, never unqualified spellings. */
+export function nativeDeclarations(project) {
+    const result = { functions: new Map(), resources: new Map(), providers: new Map(), providerMetadata: new Map(), providerDescriptors: new Map(), errors: new Map(), diagnostics: [] };
+    const issue = (span, message) => result.diagnostics.push({ ...span, code: 'NATIVE_ABI', message });
+    const sources = [];
+    const symbols = new Map();
+    if (project.library?.native)
+        sources.push({ directory: project.root, sourceRoot: project.sourceRoot, native: project.library.native, identity: project.library.name + '@' + project.library.version });
+    for (const scope of project.packages.scopes.values()) {
+        // readPackage already verified the descriptor hash; retain that source identity.
+        const native = scope.native;
+        if (native)
+            sources.push({ directory: scope.directory, sourceRoot: scope.sourceRoot, native, identity: scope.name + '@' + scope.version });
+    }
+    for (const source of sources) {
+        result.providerMetadata.set(source.identity, source.native);
+        result.providerDescriptors.set(source.identity, resolve(source.directory, source.native.bindings));
+        let descriptor;
+        try {
+            descriptor = readNativeDescriptor(source.directory, source.native);
+        }
+        catch (error) {
+            issue({ file: resolve(source.directory, source.native.bindings), start: 0, end: 0, line: 1, column: 1 }, error instanceof Error ? error.message : String(error));
+            continue;
+        }
+        for (const name of [...descriptor.resources.map(r => r.release), ...descriptor.functions.flatMap(f => [f.symbol, ...(f.result.release ? [f.result.release] : [])])]) {
+            const provider = symbols.get(name);
+            if (provider && provider !== source.identity)
+                issue({ file: resolve(source.directory, source.native.bindings), start: 0, end: 0, line: 1, column: 1 }, `Native symbol ${name} has ambiguous providers ${provider} and ${source.identity}`);
+            else
+                symbols.set(name, source.identity);
+        }
+        for (const resource of descriptor.resources) {
+            const file = resolve(source.sourceRoot, resource.module + '.aug');
+            const def = project.scopes.get(file)?.get(resource.name);
+            if (!def || def.file !== file || def.node.kind !== 'resource') {
+                issue({ file, start: 0, end: 0, line: 1, column: 1 }, 'Native descriptor has no matching resource declaration ' + resource.module + '.' + resource.name);
+                continue;
+            }
+            result.resources.set(def.node, resource);
+            result.providers.set(def.node, source.identity);
+        }
+        for (const fn of descriptor.functions) {
+            const file = resolve(source.sourceRoot, fn.module + '.aug');
+            const def = project.scopes.get(file)?.get(fn.name);
+            if (!def || def.file !== file || def.node.kind !== 'function' || !def.node.externC || def.node.valueAbi) {
+                issue({ file, start: 0, end: 0, line: 1, column: 1 }, 'Native descriptor has no matching extern C declaration ' + fn.module + '.' + fn.name);
+                continue;
+            }
+            result.functions.set(def.node, fn);
+            result.providers.set(def.node, source.identity);
+            if (fn.error) {
+                const dot = fn.error.lastIndexOf('.'), errorFile = resolve(source.sourceRoot, fn.error.slice(0, dot) + '.aug');
+                const error = project.scopes.get(errorFile)?.get(fn.error.slice(dot + 1));
+                if (!error || error.file !== errorFile || error.node.kind !== 'class')
+                    issue(def.node.span, 'Native descriptor has no matching checked error declaration ' + fn.error);
+                else
+                    result.errors.set(def.node, error);
+            }
+        }
+    }
+    for (const def of project.definitions.values())
+        if (def.node.kind === 'resource' && !result.resources.has(def.node))
+            issue(def.node.span, 'extern C resource requires a release identity in its package native.abi.json');
+    return result;
+}

package/src/native-facts.js

@@ -0,0 +1,63 @@
+/** Keep checked binding facts separate from promises made by foreign code. */
+export function nativeFact(checked, node) {
+    const provider = checked.native.providers.get(node), manifest = provider && checked.native.providerMetadata.get(provider);
+    if (!provider || !manifest)
+        return;
+    const common = { provider, profile: manifest.profile, descriptor: manifest.bindings, descriptorSha256: manifest.bindingsSha256,
+        upstream: manifest.upstream, supportedTargets: manifest.artifacts.map(artifact => artifact.target) };
+    if (node.kind === 'resource') {
+        const contract = checked.native.resources.get(node);
+        return contract ? { ...common, kind: 'resource', contract, cleanup: 'scope-exit' } : undefined;
+    }
+    const contract = checked.native.functions.get(node);
+    return contract ? { ...common, kind: 'function', contract,
+        compilerChecks: ['provider identity', 'descriptor digest', 'August signature', 'ownership at August call sites'],
+        nativeAuthorPromises: ['inputs are not retained', 'boundary entry stays on the caller thread', 'foreign threads do not enter August', 'C ABI boundary does not unwind into August'] } : undefined;
+}
+/** Resolve only standalone calls. Member dispatch is not claimed as complete. */
+export function nativeDependencies(checked, method) {
+    const found = new Map(), seen = new Set();
+    const visit = (current) => {
+        if (seen.has(current))
+            return;
+        seen.add(current);
+        const fact = nativeFact(checked, current);
+        if (fact?.kind === 'function') {
+            found.set(current, fact);
+            return;
+        }
+        const walk = (value) => {
+            if (!value || typeof value !== 'object')
+                return;
+            if (Array.isArray(value)) {
+                value.forEach(walk);
+                return;
+            }
+            const call = value;
+            if (call.kind === 'call' && call.callee?.kind === 'name' && call.span) {
+                const target = checked.project.scopes.get(call.span.file)?.get(call.callee.name);
+                if (target?.node.kind === 'function')
+                    visit(target.node);
+            }
+            for (const [key, child] of Object.entries(value))
+                if (!['span', 'nameSpan', 'sourceSpan'].includes(key))
+                    walk(child);
+        };
+        walk(current.body);
+    };
+    visit(method);
+    return [...found.values()].sort((a, b) => (a.provider + '/' + a.contract.symbol).localeCompare(b.provider + '/' + b.contract.symbol, 'en'));
+}
+export function nativeDescription(fact, contractLink) {
+    const quote = (text) => '`' + text + '`';
+    const targets = fact.supportedTargets.map(target => target.os + ' ' + target.arch + (target.minimumOS ? ' ' + target.minimumOS + '+' : '') + (target.minimumLibc ? ' glibc ' + target.minimumLibc + '+' : '') + (target.cxxABI ? ' ' + target.cxxABI : '')).join(', ');
+    const origin = `Native implementation: ${quote(fact.provider)}, ${quote(fact.upstream.version)}. Supported targets: ${targets}. Binding contract: ${contractLink ?? quote(fact.descriptor)} (SHA-256 ${quote(fact.descriptorSha256)}).`;
+    if (fact.kind === 'resource')
+        return `${origin} An owned value releases its opaque handle through ${quote(fact.contract.release)} when its scope ends, including error and return paths.`;
+    const contract = fact.contract;
+    const loans = contract.params.filter(param => param.kind === 'resource').map(param => quote(param.name) + (param.ownership === 'consume' ? ' transfers ownership' : param.ownership === 'borrow' ? ' lends mutable access for this call' : ' lends read access for this call'));
+    const result = contract.result.kind === 'resource' ? 'The caller owns the returned handle.' : contract.result.release ?
+        `August copies the returned buffer, then calls ${quote(contract.result.release)} to release it.` : '';
+    return `${origin} It calls ${quote(contract.symbol)} through the C ABI on the caller thread; a blocking native call blocks that thread. ${loans.length ? loans.join('; ') + '. ' : ''}${result ? result + ' ' : ''}` +
+        'The compiler checks the provider, descriptor digest, signature and ownership at August call sites. The native author promises not to retain inputs, enter August from foreign threads, or unwind across the C boundary; internal native workers may run. The compiler does not prove those promises.';
+}

package/src/native.js

@@ -6,6 +6,8 @@ import { createHash } from 'node:crypto';
 import { loadConfig } from "./config.js";
 import { generateOpenApi } from "./openapi.js";
 import { nativeHome } from '../scripts/native-home.mjs';
+import { nativeRequirements } from '../scripts/native-setup.mjs';
+import { cCompiler, compilerHelp } from '../scripts/native-toolchain.mjs';
 export function compileNative(root, generated, options = {}) {
     const config = loadConfig(root).config;
     const buildDir = join(root, '.aug-build', ...(options.testIndex === undefined ? [] : ['tests']));
@@ -27,38 +29,38 @@ export function compileNative(root, generated, options = {}) {
     copyFileSync(join(runtimeDir, 'aug_values.c'), valuesPath);
     const outputName = options.testIndex === undefined ? options.output ?? config.output ?? basename(root) : name;
     const output = isAbsolute(outputName) ? outputName : join(buildDir, outputName);
-    const cc = process.env.CC ?? (existsSync('/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang') ?
-        '/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang' : 'clang');
+    mkdirSync(dirname(output), { recursive: true });
+    const cc = cCompiler();
     const release = options.release ?? config.optimization === 'release';
     const args = [release ? '-O2' : '-O0', '-g', '-std=c11', '-D_POSIX_C_SOURCE=200809L', '-Wall', '-Wextra',
         '-pthread',
         cPath, runtimePath, valuesPath, ...config.library_paths.map(path => `-L${resolve(root, path)}`), ...config.libraries.map(name => `-l${name}`), '-o', output];
-    const web = generated.includes('aug_http_') || generated.includes('_aug_http_') || generated.includes('aug_headers_');
+    const needs = nativeRequirements(generated), web = needs.web;
     if (web)
         args.push('-DAUG_HTTP_RUNTIME');
-    if (generated.includes('aug_html_') || web) {
+    if (needs.html) {
         const htmlSource = join(buildDir, 'aug_html.c');
         copyFileSync(join(runtimeDir, 'aug_html.c'), htmlSource);
         args.push(htmlSource);
     }
-    if (generated.includes('_aug_time_')) {
+    if (needs.time) {
         const timeSource = join(buildDir, 'aug_time.c');
         copyFileSync(join(runtimeDir, 'aug_time.c'), timeSource);
         args.push(timeSource);
     }
-    if (web || generated.includes('aug_task_')) {
+    if (needs.tasks) {
         const taskSource = join(buildDir, 'aug_tasks.c');
         copyFileSync(join(runtimeDir, 'aug_tasks.c'), taskSource);
         const minicoro = join(nativeRoot, 'sources', 'minicoro');
         if (!existsSync(join(minicoro, 'minicoro.h')))
-            throw new Error('Task dependency is missing. Run the compiler scripts/bootstrap-native.mjs with --extract-only; AUG_NATIVE_HOME selects its directory.');
+            throw new Error('Task dependencies are missing. Run aug run to prepare them automatically, or use aug-native --extract-only --only minicoro to prewarm the cache.');
         args.push(taskSource, '-I' + minicoro, process.platform === 'darwin' ? '-D_DARWIN_C_SOURCE' : '-D_DEFAULT_SOURCE');
     }
-    if (generated.includes('_aug_crypto_') || web) {
+    if (needs.crypto) {
         const prefix = join(nativeRoot, 'prefix');
         const manifestPath = join(prefix, 'aug-native-manifest.json');
         if (!existsSync(manifestPath))
-            throw new Error('Native libraries are not ready. Run node scripts/bootstrap-native.mjs in the compiler directory; AUG_NATIVE_HOME selects its directory.');
+            throw new Error('Native libraries are not ready. Run aug run to prepare them automatically, or use aug-native to prewarm the cache.');
         const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
         if (manifest.platform !== process.platform || manifest.architecture !== process.arch)
             throw new Error(`Native dependencies target ${manifest.platform}/${manifest.architecture}; this compiler runs on ${process.platform}/${process.arch}. Build dependencies on this host.`);
@@ -74,12 +76,12 @@ export function compileNative(root, generated, options = {}) {
                 args.push('-framework', 'CoreFoundation', '-framework', 'SystemConfiguration');
         }
     }
-    if (generated.includes('_aug_json_') || generated.includes('aug_json_') || web) {
+    if (needs.json) {
         const jsonSource = join(buildDir, 'aug_json.c');
         copyFileSync(join(runtimeDir, 'aug_json.c'), jsonSource);
         const yyjson = join(nativeRoot, 'sources', 'yyjson', 'src');
         if (!existsSync(join(yyjson, 'yyjson.c')))
-            throw new Error('JSON dependency is missing. Run node scripts/bootstrap-native.mjs --extract-only.');
+            throw new Error('JSON dependencies are missing. Run aug run to prepare them automatically, or use aug-native --extract-only --only yyjson to prewarm the cache.');
         args.push(jsonSource, join(yyjson, 'yyjson.c'), '-I' + yyjson);
     }
     const sdk = '/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk';
@@ -87,8 +89,12 @@ export function compileNative(root, generated, options = {}) {
         args.unshift('-isysroot', sdk);
     const compile = spawnSync(cc, args, { encoding: 'utf8', cwd: root });
     if (compile.error)
-        throw compile.error;
-    const error = compile.status === 0 ? '' : compile.stderr || compile.stdout || 'C compiler failed';
+        throw new Error(`Cannot compile the program with ${cc}: ${compile.error.message}.\n${compilerHelp()}`);
+    const detail = (compile.stderr || compile.stdout || (compile.signal ? `Compiler stopped by ${compile.signal}` : 'C compiler failed')).trim();
+    const error = compile.status === 0 ? '' : `Native compilation failed with ${cc}.\n${detail}\n` +
+        (/cannot find -l|library not found|file not found|No such file/.test(detail) ?
+            'Check main.yaml libraries/library_paths and the named header or library. On Linux, HTTP also needs zlib development headers.\n' : '') +
+        `Generated C: ${cPath}\nIf this is valid August code without external C declarations, please report it with this compiler output.`;
     const diagnostics = [];
     for (const match of error.matchAll(/^(.+\.aug):(\d+):(\d+):\s*(?:fatal )?error:\s*(.+)$/gm))
         diagnostics.push({ file: match[1], line: Number(match[2]), column: Number(match[3]), code: 'NATIVE', message: match[4] });

package/src/navigation.js

@@ -2,6 +2,7 @@ import { statSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { lex } from "./lexer.js";
 import { libraryChild } from "./libraries.js";
+import { isGitSource, sourceAlias } from "./git-packages.js";
 function definitionTarget(def) {
     const span = def.node.kind === 'interceptor' ? def.node.nameSpan : def.node.span;
     return { name: def.name, file: def.file, line: span.line,
@@ -41,7 +42,8 @@ function importPathTarget(project, importer, from, name, segment) {
         return exportTarget(project, folder, name, segment < from.length - 1 ? from[segment + 1] : undefined);
     }
     const owner = importer.package ? project.packages.scopes.get(importer.package) : undefined;
-    const dependency = owner ? project.packages.scopes.get(owner.dependencies[from[0]]) : project.packages.roots.get(from[0]);
+    const alias = isGitSource(from[0]) ? sourceAlias(from[0]) : from[0];
+    const dependency = owner ? project.packages.scopes.get(owner.dependencies[alias]) : project.packages.roots.get(alias);
     if (dependency) {
         const folder = join(dependency.sourceRoot, ...from.slice(1, segment + 1));
         return exportTarget(project, folder, name, segment < from.length - 1 ? from[segment + 1] : undefined);
@@ -128,7 +130,7 @@ export function definitionAt(project, fileName, offset) {
             entry.span.end <= item.span.end);
         const fromIndex = declarationTokens.findIndex(entry => entry.kind === 'from');
         const sourceTokens = declarationTokens.slice(fromIndex + 1)
-            .filter(entry => entry.kind === 'identifier');
+            .filter(entry => entry.kind === 'identifier' || entry.kind === 'string');
         const segments = item.kind === 'import' ? item.from : [item.from];
         const selected = token.kind === 'from' ? segments.length - 1 :
             sourceTokens.findIndex((entry) => entry === token);

package/src/openapi.js

@@ -1,3 +1,4 @@
+import { callableResult } from "./contracts.js";
 import { createHash } from 'node:crypto';
 import { schemaType } from "./schemas.js";
 import { callableDocumentation } from "./documentation.js";
@@ -81,7 +82,7 @@ export function generateOpenApi(checked) {
                 result.push({ status: fn.endpoint?.status ?? 200, type: primitive('void') });
                 return;
             }
-            const type = checked.expressionTypes.get(expr) ?? schemaType(project, fn.returns, fn.span.file);
+            const type = checked.expressionTypes.get(expr) ?? callableResult(checked, fn);
             if (expr.kind === 'call' && expr.callee.kind === 'name' && type.name === 'HttpResponse') {
                 if (expr.callee.name !== 'HttpResponse') {
                     const def = project.scopes.get(fn.span.file)?.get(expr.callee.name);
@@ -125,8 +126,8 @@ export function generateOpenApi(checked) {
             }
             result.push({ status: fn.endpoint?.status ?? 200, type });
         });
-        if (!result.length && fn.returns.name !== 'HttpResponse')
-            result.push({ status: fn.endpoint?.status ?? 200, type: schemaType(project, fn.returns, fn.span.file) });
+        if (!result.length && callableResult(checked, fn).name !== 'HttpResponse')
+            result.push({ status: fn.endpoint?.status ?? 200, type: callableResult(checked, fn) });
         return result;
     };
     const served = new Map();
@@ -152,7 +153,7 @@ export function generateOpenApi(checked) {
                 current.schema = { oneOf: [current.schema, value] };
         };
         if (endpoint.streams) {
-            const item = schemaType(project, fn.returns, fn.span.file), sse = item.name === 'ServerEvent';
+            const item = callableResult(checked, fn), sse = item.name === 'ServerEvent';
             const itemSchema = sse ? { type: 'object', required: ['data'], properties: { data: { type: 'string', contentMediaType: 'application/json', contentSchema: schema(item.args[0], fn.span) }, id: { type: 'string' }, event: { type: 'string' }, retry: { type: 'integer', minimum: 0 } } } : schema(item, fn.span);
             responses[endpoint.status] = { description: 'Streaming response', content: { [sse ? 'text/event-stream' : item.name === 'Html' ? 'text/html' : 'application/octet-stream']: { itemSchema } } };
         }