@greenpandastudios/aug-cli 0.20.1 → 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/package-locking.js

@@ -43,3 +43,46 @@ export function withPackageLock(path, action) {
         rmSync(path, { recursive: true, force: true });
     }
 }
+/** Network-backed installs keep the writer lock until the asynchronous action completes. */
+export async function withPackageLockAsync(path, action) {
+    const deadline = Date.now() + 30000;
+    while (true) {
+        try {
+            mkdirSync(path);
+            break;
+        }
+        catch (error) {
+            if (!error || typeof error !== 'object' || !('code' in error) || error.code !== 'EEXIST')
+                throw error;
+            let stale = false;
+            try {
+                const pid = Number(readFileSync(join(path, 'pid'), 'utf8'));
+                if (!Number.isSafeInteger(pid) || pid < 1)
+                    throw new Error('Invalid lock owner');
+                try {
+                    process.kill(pid, 0);
+                }
+                catch (e) {
+                    stale = !!e && typeof e === 'object' && 'code' in e && e.code === 'ESRCH';
+                }
+            }
+            catch {
+                stale = existsSync(path) && Date.now() - statSync(path).mtimeMs > 180000;
+            }
+            if (stale) {
+                rmSync(path, { recursive: true, force: true });
+                continue;
+            }
+            if (Date.now() >= deadline)
+                throw new Error('Another August installation is still running. Lock: ' + path);
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+    }
+    try {
+        writeFileSync(join(path, 'pid'), String(process.pid));
+        return await action();
+    }
+    finally {
+        rmSync(path, { recursive: true, force: true });
+    }
+}

package/src/package-manager.js

@@ -8,6 +8,7 @@ import { parse } from "./parser.js";
 import { isGitSource, materializeGit, sourceAlias } from "./git-packages.js";
 import { agentInstructions } from "./project-init.js";
 import { withPackageLock } from "./package-locking.js";
+import { validateNativeManifest, readNativeDescriptor } from "./native-contracts.js";
 export const compilerVersion = () => JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 export const packageAlias = (name) => /^[a-z][a-z0-9_]*$/.test(name) && name !== 'august';
 /** Repository imports declare their dependencies beside the code that uses them. */
@@ -71,9 +72,15 @@ export function readPackage(directory) {
         format: 1, name: 'aug-' + sourceAlias(realpathSync(directory)), version: '0.0.0', compiler: compilerVersion(),
         source: existsSync(join(directory, 'export.aug')) ? '.' : 'src', dependencies: {}
     };
-    if (manifest.format !== 1 || !npmName.test(manifest.name ?? '') || !version.test(manifest.version ?? '') ||
+    if (![1, 2].includes(manifest.format) || !npmName.test(manifest.name ?? '') || !version.test(manifest.version ?? '') ||
         manifest.compiler !== compilerVersion())
         throw new Error(`Invalid August package or compiler mismatch in ${directory}; expected compiler ${compilerVersion()}`);
+    if (manifest.format === 1 && manifest.native !== undefined)
+        throw new Error('Native packages require manifest format 2');
+    if (manifest.format === 2) {
+        manifest.native = validateNativeManifest(manifest.native);
+        readNativeDescriptor(directory, manifest.native);
+    }
     if (typeof manifest.source !== 'string' || !manifest.source || isAbsolute(manifest.source))
         throw new Error('Package source must be a relative folder');
     const sourceRoot = realpathSync(resolve(directory, manifest.source));
@@ -127,7 +134,7 @@ function normalizeSpecifier(spec, root, requirePath = true) {
 }
 function packageDigest(directory, sourceRoot) {
     const hash = createHash('sha256');
-    for (const file of [join(directory, 'aug-package.json'), join(directory, 'package.json'), ...sourcePaths(sourceRoot)].filter(existsSync).sort()) {
+    for (const file of [join(directory, 'aug-package.json'), join(directory, 'package.json'), join(directory, 'native.abi.json'), join(directory, 'THIRD_PARTY_NOTICES.md'), ...sourcePaths(sourceRoot)].filter(existsSync).sort()) {
         hash.update(relative(directory, file).replaceAll('\\', '/'));
         hash.update('\0');
         hash.update(readFileSync(file));
@@ -156,10 +163,12 @@ export function projectPackages(root, specifications, sourceFolder = root) {
             if (manifest.name !== entry.name || manifest.version !== entry.version || manifest.source !== entry.source ||
                 packageDigest(directory, sourceRoot) !== entry.digest)
                 throw new Error(`Installed ${entry.name} changed; run aug install`);
+            if (JSON.stringify(entry.native) !== JSON.stringify(manifest.native))
+                throw new Error(`NATIVE_LOCK: Native metadata for ${entry.name} differs from its verified source manifest; run aug install`);
             if (result.scopes.has(entry.path))
                 throw new Error('Duplicate package lock path');
             manifests.set(entry.path, manifest);
-            result.scopes.set(entry.path, { ...entry, directory, sourceRoot, specifications: manifest.dependencies ?? {} });
+            result.scopes.set(entry.path, { ...entry, native: manifest.native, directory, sourceRoot, specifications: manifest.dependencies ?? {} });
         }
         verifyIdentities(lock.packages);
         for (const scope of result.scopes.values()) {
@@ -212,14 +221,12 @@ function npm(args, cwd) {
     return process.stdout;
 }
 /** Running an application prepares its declared packages; checking remains read-only. */
-export function prepareRunPackages(root, offline = false) {
+export function prepareRunPackages(root, offline = false, frozen = false) {
     const loaded = loadConfig(root);
     if (loaded.diagnostics.length)
         return; // The checker renders the configuration's source diagnostics.
     const library = isLibrary(root) ? readPackage(root) : undefined;
     const specifications = packageSpecifications(library?.sourceRoot ?? root, library?.manifest.dependencies ?? loaded.config.packages);
-    if (!Object.keys(specifications).length)
-        return;
     const lockPath = join(root, 'aug.lock.json');
     let lock;
     if (existsSync(lockPath)) {
@@ -234,6 +241,10 @@ export function prepareRunPackages(root, offline = false) {
     }
     const matching = lock?.compiler === compilerVersion() && sameSpecifications(lock.specifications, specifications);
     if (!matching) {
+        if (!lock && !Object.keys(specifications).length)
+            return;
+        if (frozen)
+            throw new Error('PACKAGE_LOCK: Frozen run requires a matching aug.lock.json for the current imports, configuration and compiler. Run aug install before retrying.');
         process.stderr.write('Installing August packages declared by imports and main.yaml…\n');
         installPackages(root, false, offline);
         return;
@@ -272,7 +283,7 @@ function installLocked(root, frozen, offline, update) {
 }
 const isLibrary = (root) => existsSync(join(root, 'aug-package.json')) ||
     !existsSync(join(root, 'main.aug')) && (existsSync(join(root, 'export.aug')) || existsSync(join(root, 'src/export.aug')));
-const selectedSource = (file) => file.endsWith('.aug') || ['aug-package.json', 'package.json', 'main.yaml', 'README.md', 'LICENSE'].includes(file);
+const selectedSource = (file) => file.endsWith('.aug') || ['aug-package.json', 'package.json', 'main.yaml', 'README.md', 'LICENSE', 'native.abi.json', 'THIRD_PARTY_NOTICES.md'].includes(file);
 function copySource(origin, destination) {
     let bytes = 0, count = 0;
     const copy = (folder) => {
@@ -381,7 +392,7 @@ function installSourceGraph(root, specifications, frozen, offline, previous) {
         writeJson(join(directory, 'package.json'), { name: manifest.name, version: manifest.version, private: true, dependencies });
         const { sourceRoot } = readPackage(directory);
         const entry = { path, name: manifest.name, version: manifest.version, source: manifest.source,
-            digest: packageDigest(directory, sourceRoot), dependencies: {} };
+            digest: packageDigest(directory, sourceRoot), dependencies: {}, ...(manifest.native ? { native: manifest.native } : {}) };
         packages.set(path, entry);
         for (const [alias, request] of Object.entries(dependencies)) {
             entry.dependencies[alias] = visit(request, origin);
@@ -395,6 +406,8 @@ function installSourceGraph(root, specifications, frozen, offline, previous) {
         const lock = { format: 1, compiler: compilerVersion(), specifications, roots, npm: registry,
             git: [...gitSources.values()].sort((a, b) => a.request.localeCompare(b.request)),
             packages: [...packages.values()].sort((a, b) => a.path.localeCompare(b.path)) };
+        if (previous?.native && JSON.stringify(lock.packages) === JSON.stringify(previous.packages))
+            lock.native = previous.native;
         if (frozen && JSON.stringify(lock.packages) !== JSON.stringify(previous?.packages))
             throw new Error('Frozen package contents changed; use aug install --update to choose new revisions.');
         rmSync(join(stage, 'transport'), { recursive: true, force: true });
@@ -446,6 +459,8 @@ export function preparePackage(root) {
     transport.version = manifest.version;
     transport.dependencies = manifest.dependencies ?? {};
     transport.files = [...new Set([...(Array.isArray(transport.files) ? transport.files : ['README.md', 'LICENSE']), manifest.source, '.aug-spec', 'aug-package.json'])];
+    if (manifest.native)
+        transport.files.push('native.abi.json', 'THIRD_PARTY_NOTICES.md');
     writeJson(join(root, 'package.json'), transport);
     readPackage(root);
 }

package/src/parser.js

@@ -218,8 +218,14 @@ class Parser {
             return { kind: 'composition', name, typeParams: [], bindings, span: this.span(start) };
         }
         if (this.at('extern')) {
-            this.take();
+            const start = this.take().span;
             this.expect('C');
+            if (this.current().value === 'resource') {
+                this.take();
+                const name = this.expect('identifier').value;
+                this.endStatement();
+                return { kind: 'resource', name, typeParams: [], span: this.span(start) };
+            }
             return this.parseFunction(true);
         }
         if (this.looksLikeBareClass())
@@ -395,6 +401,11 @@ class Parser {
             this.parseTypeParams();
             if (this.at('('))
                 this.parseParams(true);
+            if (this.match('unless')) {
+                this.parseType();
+                while (this.match('and') || this.match(','))
+                    this.parseType();
+            }
             if (this.match('=>')) {
                 return true;
             }
@@ -497,6 +508,13 @@ class Parser {
         const name = this.expect('identifier').value;
         const { typeParams, typeConstraints, typeVariance } = this.parseTypeParams();
         const fields = this.at('(') ? this.parseParams(true) : [];
+        const validationErrors = [];
+        const validationDeclared = !!this.match('unless');
+        if (validationDeclared) {
+            validationErrors.push(this.parseType());
+            while (this.match('and') || this.match(','))
+                validationErrors.push(this.parseType());
+        }
         let constructorBody = this.match('=>') ? this.parseBlock(start) : undefined;
         const implemented = [];
         if (!this.at('implements'))
@@ -542,7 +560,7 @@ class Parser {
         }
         this.closeBrace();
         return { kind: 'class', name, typeParams, typeConstraints, typeVariance, fields, stateFields, constructorBody,
-            implements: implemented, methods, headerEnd, span: this.span(start) };
+            validationErrors, validationDeclared, implements: implemented, methods, headerEnd, span: this.span(start) };
     }
     parseInterface() {
         const keyword = this.take();