@greenpandastudios/aug-cli 0.20.1 → 0.21.0

package/src/codegen.js

@@ -206,7 +206,8 @@ class CGenerator {
             `  AugValue value = roots[${cls.fields.length}];`,
             `  value.as.object->field_names = ${this.name(def)}_field_names;`,
             ...(cls.kind === 'class' && initializationOf(cls).length ? [`  ${this.initializerName(def)}(value, NULL, 0);`] : []),
-            ...(cls.kind === 'class' && cls.record ? ['  aug_freeze(value);'] : []),
+            `  if (aug_has_error) { aug_drop_partial(value); value = aug_scalar_null(); }`,
+            ...(cls.kind === 'class' && cls.record ? ['  if (!aug_has_error) aug_freeze(value);'] : []),
             `  aug_frame_leave(&frame);`,
             `  return value;`,
             `}`,
@@ -377,18 +378,25 @@ class BodyEmitter {
     locals = new Map();
     owned = new Set();
     classFields = new Map();
+    ownedClassFields = new Set();
     scalarSlots = new Set();
     slots = 1;
     labelCounter = 0;
     errorTarget = 'aug_cleanup';
     returnTarget = 'aug_cleanup';
     continuation;
+    constructionNext = false;
+    constructorResults = new Set();
     constructor(generator, file, def, owner) {
         this.generator = generator;
         this.file = file;
         this.def = def;
         if (owner)
-            fieldsOf(owner).forEach((field, index) => this.classFields.set(field.name, index));
+            fieldsOf(owner).forEach((field, index) => {
+                this.classFields.set(field.name, index);
+                if (field.ownership === 'own')
+                    this.ownedClassFields.add(field.name);
+            });
     }
     addParameter(name, index, owned = false) {
         const slot = this.newSlot();
@@ -398,6 +406,7 @@ class BodyEmitter {
             this.owned.add(slot);
     }
     initializeInterceptor(layer, params, name, method) {
+        this.constructionNext = layer.constructorResultFresh === true;
         const receiver = method ? this.newSlot() : undefined;
         if (receiver !== undefined)
             this.line(`${this.slot(receiver)} = self;`);
@@ -448,6 +457,8 @@ class BodyEmitter {
         const slot = this.newSlot();
         this.line(`${this.slot(slot)} = ${next.target}(${next.receiver === undefined ? '' :
             `${this.slot(next.receiver)}, `}${array}, ${args.length});`);
+        if (this.constructionNext)
+            this.constructorResults.add(slot);
         this.line(`if (aug_has_error) goto ${this.errorTarget};`);
         return slot;
     }
@@ -478,7 +489,8 @@ class BodyEmitter {
         if (expr.kind === 'handle' && expr.call.kind === 'call') {
             const plan = this.generator.actionPlan(expr), endpoint = plan.endpoint.node.endpoint;
             const metadata = { method: endpoint.method, path: endpoint.path, parameters: plan.parameters.map(({ param, type, form }) => ({ name: param.source?.name ?? param.name, source: param.source?.kind, form, schema: this.generator.actionSchema(type) })) };
-            const args = plan.parameters.map(parameter => parameter.form || parameter.source === undefined ? undefined : this.emitExpr(expr.call.args[parameter.source]));
+            const values = expr.call.args.map(argument => argument.kind === 'formInput' ? undefined : this.emitExpr(argument));
+            const args = plan.parameters.map(parameter => parameter.form || parameter.source === undefined ? undefined : values[parameter.source]);
             const array = this.label('action_values'), slot = this.newSlot();
             this.line(`AugValue ${array}[] = {${args.map(arg => arg === undefined ? 'aug_null()' : this.slot(arg)).join(', ') || 'aug_scalar_null()'}};`);
             this.line(`${this.slot(slot)} = aug_http_action(${cString(JSON.stringify(metadata))}, ${array}, ${args.length});`);
@@ -513,7 +525,9 @@ class BodyEmitter {
             thunk.line(`${thunk.slot(0)} = ${thunk.slot(result)};`);
             const name = this.generator.taskThunk(thunk, args.length), array = this.label('task_args'), slot = this.newSlot();
             this.line(`AugValue ${array}[] = {${args.map(arg => this.slot(arg)).join(', ') || 'aug_scalar_null()'}};`);
-            this.line(`${this.slot(slot)} = aug_task_start(${name}, ${receiver === undefined ? 'aug_scalar_null()' : this.slot(receiver)}, ${array}, ${args.length});`);
+            const captures = this.label('task_owned');
+            this.line(`const unsigned char ${captures}[] = {${args.map((_, i) => this.generator.callPlan(call)?.ownerships?.[i] === 'own' ? '1' : '0').join(', ') || '0'}};`);
+            this.line(`${this.slot(slot)} = aug_task_start_owned(${name}, ${receiver === undefined ? 'aug_scalar_null()' : this.slot(receiver)}, ${array}, ${args.length}, ${captures});`);
             this.clearMovedArgs(call, (this.generator.callPlan(call)?.ownerships ?? []).map(ownership => ({ ownership: ownership ?? 'managed' })));
             this.line(`if (aug_has_error) goto ${this.errorTarget};`);
             return slot;
@@ -946,6 +960,8 @@ class BodyEmitter {
                 this.line(`aug_set_field(${this.slot(object)}, ${this.memberIndex(stmt.target.object, stmt.target.name)}, ${this.slot(value)});`);
             }
             let targetOwns = stmt.ownership === 'own';
+            if (stmt.target.kind === 'name' && !this.locals.has(stmt.target.name))
+                targetOwns ||= this.ownedClassFields.has(stmt.target.name);
             if (stmt.target.kind === 'member') {
                 const memberName = stmt.target.name;
                 const node = this.generator.expressionType(stmt.target.object)?.def?.node;
@@ -1058,6 +1074,7 @@ class BodyEmitter {
     }
     emitTryAlways(stmt) {
         const outerError = this.errorTarget, outerReturn = this.returnTarget;
+        const ownedBefore = new Set(this.owned);
         const caught = this.label('aug_final_catch'), failed = this.label('aug_final_error'), returned = this.label('aug_final_return');
         const cleanup = this.label('aug_always'), done = this.label('aug_always_done'), after = this.label('aug_always_after');
         const reason = this.label('aug_exit_reason'), depth = this.label('aug_final_depth'), cancellation = this.label('aug_final_cancel');
@@ -1070,8 +1087,11 @@ class BodyEmitter {
         this.emitScoped(stmt.body);
         this.line(`goto ${cleanup};`);
         this.line(`${caught}:;`);
-        this.line(`aug_scope_restore(${depth}); if (aug_cancelled) goto ${failed};`);
         this.line(`aug_lock_restore(${locks});`);
+        this.line(`aug_scope_restore(${depth}); if (aug_cancelled) goto ${failed};`);
+        for (const slot of this.owned)
+            if (!ownedBefore.has(slot))
+                this.line(`aug_drop(${this.slot(slot)}); ${this.slot(slot)} = aug_scalar_null();`);
         this.errorTarget = failed;
         for (const clause of stmt.catches) {
             this.line(`if (aug_error_is(${cString(clause.type.name)})) {`);
@@ -1087,8 +1107,12 @@ class BodyEmitter {
         this.line(`${returned}: ${reason} = 1; goto ${cleanup};`);
         this.line(`${failed}: ${reason} = 2;`);
         this.line(`${cleanup}:;`);
-        this.line(`aug_scope_restore(${depth}); ${this.slot(pending)} = aug_has_error ? aug_take_error() : aug_scalar_null();`);
         this.line(`aug_lock_restore(${locks});`);
+        this.line(`aug_scope_restore(${depth});`);
+        for (const slot of this.owned)
+            if (!ownedBefore.has(slot))
+                this.line(`aug_drop(${this.slot(slot)}); ${this.slot(slot)} = aug_scalar_null();`);
+        this.line(`${this.slot(pending)} = aug_has_error ? aug_take_error() : aug_scalar_null();`);
         this.line(`${cancellation} = aug_cancelled; aug_cancelled = false;`);
         this.errorTarget = done;
         this.returnTarget = done;
@@ -1149,6 +1173,7 @@ class BodyEmitter {
             `  aug_lock_restore(aug_lock_base);`,
             `  aug_scope_join_to(aug_scope_base);`,
             ownedCleanup,
+            ...[...this.constructorResults].map(slot => `  aug_constructor_result_cleanup(${this.slot(slot)}, ${this.slot(0)});`),
             `  aug_scope_restore(aug_scope_base);`,
             `  AugValue result = ${this.slot(0)};`,
             `  aug_frame_leave(&frame);`,

package/src/compiler-packs.js

@@ -0,0 +1,66 @@
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { compilerVersion } from "./package-manager.js";
+import { ensureVerifiedArchive } from "./native-artifacts.js";
+import { nativeHostTarget } from "./native-contracts.js";
+import { withPackageLockAsync } from "./package-locking.js";
+import { readRuntimePack } from "./llvm-native.js";
+import { llvmPlatform } from "./llvm-platform.js";
+/** The CLI owns installation. Packages cannot choose or execute a compiler driver. */
+export async function prepareLLVMCompiler(offline = false, project) {
+    const compilerRoot = resolve(fileURLToPath(new URL('..', import.meta.url)));
+    const platform = llvmPlatform();
+    if (process.env.AUG_LLVM_HOME) {
+        const tools = resolve(process.env.AUG_LLVM_HOME), runtime = resolve(process.env.AUG_RUNTIME_PACK ?? join(compilerRoot, '.aug-native/llvm/runtime'));
+        const version = spawnSync(join(tools, 'bin/llc'), ['--version'], { encoding: 'utf8' });
+        if (version.status !== 0 || !version.stdout.includes('LLVM version 23.1.2'))
+            throw new Error('LLVM_TOOLS: Contributor override requires LLVM 23.1.2');
+        readRuntimePack(runtime);
+        if (project?.frozen)
+            throw new Error('LLVM_LOCK: A frozen build requires the pinned compiler pack. Remove contributor toolchain overrides.');
+        return { tools, runtime, developmentOverride: true };
+    }
+    const file = join(compilerRoot, 'native/compiler-packs.json');
+    if (!existsSync(file))
+        throw new Error('LLVM_TOOLS: This compiler has no published LLVM tool manifest. Install the matching LLVM preview release.');
+    const manifest = JSON.parse(readFileSync(file, 'utf8'));
+    if (manifest.format !== 1 || manifest.compiler !== compilerVersion() || manifest.llvm !== '23.1.2' || !Array.isArray(manifest.packs))
+        throw new Error('LLVM_TOOLS: Invalid compiler-owned LLVM manifest');
+    const host = process.platform + '-' + process.arch, target = nativeHostTarget(), pack = manifest.packs.find(p => p.host === host && p.target === target.triple);
+    if (!pack)
+        throw new Error('NATIVE_TARGET: No compiler pack is published for ' + platform.host + '. Available compiler packs: ' + manifest.packs.map(p => p.host).join(', '));
+    if (pack.minimumOS !== platform.minimumOS || pack.minimumLibc !== platform.minimumLibc)
+        throw new Error('LLVM_TOOLS: Compiler manifest has a different platform baseline');
+    const prepare = async () => {
+        const lockFile = project ? join(project.root, 'aug.lock.json') : undefined, initial = lockFile && existsSync(lockFile) ? readFileSync(lockFile, 'utf8') : undefined;
+        const lock = initial ? JSON.parse(initial) : { format: 1, compiler: compilerVersion(), specifications: {}, roots: {}, packages: [], npm: {} };
+        if (lock.compiler !== compilerVersion())
+            throw new Error('LLVM_LOCK: Project lock belongs to another compiler. Run aug install.');
+        const previous = lock.native?.compilers?.[host];
+        if (project?.frozen && (!previous || previous.artifactSha256 !== pack.archive.sha256))
+            throw new Error('LLVM_LOCK: Frozen build has no matching compiler artifact for ' + host + '. Run aug build --backend llvm online once on this host.');
+        const directory = await ensureVerifiedArchive(pack.archive, { offline, executables: platform.tools.map(tool => 'bin/' + tool) });
+        const identity = JSON.parse(readFileSync(join(directory, 'compiler-pack.json'), 'utf8'));
+        if (identity.format !== 1 || identity.compiler !== manifest.compiler || identity.llvm !== manifest.llvm || identity.host !== host || identity.target !== target.triple)
+            throw new Error('LLVM_TOOLS: Verified archive has a different compiler/host/target identity');
+        const runtime = readRuntimePack(join(directory, 'runtime'));
+        if (identity.runtime !== runtime.sourceSha256)
+            throw new Error('LLVM_TOOLS: Compiler pack runtime identity differs from its runtime manifest');
+        const selection = { version: manifest.compiler, llvm: manifest.llvm, host, target: target.triple, artifactSha256: pack.archive.sha256, runtimeSha256: runtime.sourceSha256 };
+        if (project?.frozen && JSON.stringify(previous) !== JSON.stringify(selection))
+            throw new Error('LLVM_LOCK: Frozen compiler/runtime identity changed for ' + host);
+        if (lockFile && !project?.frozen) {
+            lock.native ??= { format: 1, targets: {} };
+            lock.native.compilers ??= {};
+            lock.native.compilers[host] = selection;
+            if ((existsSync(lockFile) ? readFileSync(lockFile, 'utf8') : undefined) !== initial)
+                throw new Error('LLVM_LOCK: Source lock changed during compiler installation; retry');
+            writeFileSync(lockFile + '.llvm.tmp', JSON.stringify(lock, null, 2) + '\n');
+            renameSync(lockFile + '.llvm.tmp', lockFile);
+        }
+        return { tools: directory, runtime: join(directory, 'runtime'), archiveSha256: pack.archive.sha256, developmentOverride: false };
+    };
+    return project ? withPackageLockAsync(join(project.root, '.aug-install.lock'), prepare) : prepare();
+}

package/src/config.js

@@ -101,7 +101,7 @@ export function loadConfig(root) {
             }
             continue;
         }
-        if (!entry || !(entry[1] in config || entry[1] === 'output')) {
+        if (!entry || !(entry[1] in config || ['output', 'backend'].includes(entry[1]))) {
             report(index + 1, `Unsupported configuration line ${JSON.stringify(raw)}`);
             continue;
         }
@@ -131,7 +131,7 @@ export function loadConfig(root) {
                 config[key] = Number(value);
         }
         else {
-            const choices = { optimization: ['debug', 'release'], assignment: ['equals', 'to'],
+            const choices = { backend: ['c', 'llvm'], optimization: ['debug', 'release'], assignment: ['equals', 'to'],
                 block_style: ['braces', 'indent'], indentation: ['spaces', 'tabs'] };
             if (!value || choices[key] && !choices[key].includes(value))
                 report(index + 1, `${key} needs ${choices[key]?.join(' or ') ?? 'a value'}`);

package/src/editor.js

@@ -15,6 +15,8 @@ import { builtinTypes } from "./builtins.js";
 import { libraryChild, libraryRelative } from "./libraries.js";
 import { importSource, isGitSource, sourceAlias } from "./git-packages.js";
 import { snippetBody, snippetCatalog } from "./snippets.js";
+import { nativeFact, nativeDependencies, nativeDescription } from "./native-facts.js";
+import { pathToFileURL } from 'node:url';
 const builtins = [
     ...builtinFunctions.map(operation => {
         const parameters = operation.parameters.map(param => `${param.label}=${param.type}`);
@@ -132,9 +134,10 @@ function methodItem(checked, method, kind, owner) {
     const contract = checked.effectContracts.get(method);
     const effects = contract ? `${contract.inferred ? 'Inferred capabilities; effective' : 'Effective'} contract: changes ${contract.changes.join(', ') || 'nothing'}; capabilities ` +
         `${[...contract.uses.values()].map(effect => `${effect.source}.${effect.operation}`).join(', ') || 'none'}.` : '';
+    const native = nativeDependencies(checked, method).map(fact => nativeDescription(fact, '[`native.abi.json`](' + pathToFileURL(checked.native.providerDescriptors.get(fact.provider)).href + ')')).join('\n\n');
     return { label: method.name, kind, detail: label, signature: signature(method, true, errors, checked),
         documentation: [doc?.markdown, isPrivateName(method.name) ? 'Private to its declaring type.' : '',
-            injectionHelp, effects, interceptorDescription(checked, method), 'Call arguments require labels; their order does not matter.']
+            injectionHelp, effects, native, interceptorDescription(checked, method), 'Call arguments require labels; their order does not matter.']
             .filter(Boolean).join('\n\n'),
         parameters: method.params.filter(param => !param.injected)
             .map(param => `${param.label ?? param.name}=${typeName(param.type)}`),
@@ -143,6 +146,11 @@ function methodItem(checked, method, kind, owner) {
 }
 function definitionItem(checked, def) {
     const node = def.node;
+    if (node.kind === 'resource') {
+        const native = nativeFact(checked, node);
+        return { label: def.name, kind: 'type', detail: 'extern C resource ' + def.name,
+            documentation: native ? nativeDescription(native, '[`native.abi.json`](' + pathToFileURL(checked.native.providerDescriptors.get(native.provider)).href + ')') : 'Opaque native resource. Its package must declare a release identity.' };
+    }
     if (node.kind === 'function')
         return methodItem(checked, node, 'function');
     if (node.kind === 'interface')
@@ -175,10 +183,11 @@ function definitionItem(checked, def) {
     const explicit = node.fields.filter(field => !field.injected);
     const callSignature = `${def.name}${node.typeParams.length ? `<${node.typeParams.join(', ')}>` : ''}` +
         `(${explicit.map(field => `${field.label ?? field.name}=${typeName(field.type)}`).join(', ')})`;
-    const errors = [...new Set((checked.interceptorPlans.get(node) ?? []).flatMap(layer => layer.errors.map(tyName)))];
+    const errors = [...new Set([...(checked.constructorContracts.get(node)?.errors.map(tyName) ?? node.validationErrors?.map(typeName) ?? []),
+            ...(checked.interceptorPlans.get(node) ?? []).flatMap(layer => layer.errors.map(tyName))])];
     return { label: def.name, kind: 'class', detail: `${node.record ? 'record ' : ''}${label}` +
-            (node.implements.length ? ` implements ${node.implements.map(typeName).join(' and ')}` : '') +
-            (errors.length ? ` unless ${errors.join(', ')}` : ''),
+            (errors.length ? ` unless ${errors.join(' and ')}` : '') +
+            (node.implements.length ? ` implements ${node.implements.map(typeName).join(', ')}` : ''),
         signature: callSignature + (errors.length ? ` unless ${errors.join(', ')}` : ''), parameters: explicit.map(field => `${field.label ?? field.name}=${typeName(field.type)}`),
         documentation: [doc?.markdown,
             node.fields.some(field => field.injected) ? `Injected from bindings: ${node.fields.filter(field => field.injected).map(parameterText).join(', ')}.` : '',
@@ -189,7 +198,7 @@ function definitionItem(checked, def) {
 function typeFromRef(checked, file, ref) {
     const def = checked.project.scopes.get(file)?.get(ref.name);
     return { id: def?.id ?? `builtin:${ref.name}`, name: ref.name,
-        kind: def?.node.kind === 'class' || def?.node.kind === 'interface' || def?.node.kind === 'interceptor' ? def.node.kind : 'builtin',
+        kind: def?.node.kind === 'class' || def?.node.kind === 'interface' || def?.node.kind === 'interceptor' || def?.node.kind === 'resource' ? def.node.kind : 'builtin',
         args: ref.args.map(arg => typeFromRef(checked, file, arg)), nullable: ref.nullable, def };
 }
 function collectLocals(checked, file, offset) {
@@ -826,7 +835,7 @@ export function semanticTokens(checked, fileName) {
         else {
             const def = scope?.get(token.value);
             if (def)
-                type = def.node.kind === 'interceptor' ? 'decorator' : def.node.kind === 'composition' ? 'function' : def.node.kind;
+                type = def.node.kind === 'resource' ? 'type' : def.node.kind === 'interceptor' ? 'decorator' : def.node.kind === 'composition' ? 'function' : def.node.kind;
         }
         if (type)
             result.push({ line: token.span.line - 1, start: token.span.column - 1,

package/src/formatter.js

@@ -254,20 +254,22 @@ class Printer {
                 (item.lifetime ? ' ' + item.lifetime : '') + (item.sharedMutation ? ' mutable' : ''));
         else if (item.kind === 'composition')
             this.block('composition ' + item.name, () => item.bindings.forEach(binding => this.item(binding)), item.span);
+        else if (item.kind === 'resource')
+            this.line('extern C resource ' + item.name);
         else if (item.kind === 'function')
             this.method(item);
         else if (item.kind === 'class') {
             this.annotations(item.annotations);
             const header = `${item.record ? 'record ' : ''}${item.name}${this.generics(item)}(${item.fields.map(field => this.param(field, true)).join(', ')})`;
+            const errors = item.validationErrors?.length ? ` unless ${item.validationErrors.map(typeName).join(' and ')}` : '';
             if (item.record) {
-                const errors = item.validationErrors?.length ? ` unless ${item.validationErrors.map(typeName).join(' and ')}` : '';
                 if (item.constructorBody)
                     this.block(header + errors, () => this.initializer(item), item.span);
                 else
                     this.line(header + errors);
             }
             else {
-                this.block(header + ' implements ' + item.implements.map(typeName).join(', '), () => {
+                this.block(header + errors + ' implements ' + item.implements.map(typeName).join(', '), () => {
                     for (const field of item.stateFields ?? []) {
                         this.before(field.span.start);
                         this.line(`${field.mutable ? 'mutable ' : ''}${typeName(field.type)} ${field.name} = ${this.expression(field.initializer)}`);

package/src/git-http.js

@@ -0,0 +1,137 @@
+import { createHash } from 'node:crypto';
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { gitReference, sourceAlias } from "./git-packages.js";
+import { withPackageLockAsync } from "./package-locking.js";
+const selected = (name) => !name.split('/').some(part => part.startsWith('.')) && (name.endsWith('.aug') || ['aug-package.json', 'package.json', 'main.yaml', 'README.md', 'LICENSE', 'native.abi.json', 'THIRD_PARTY_NOTICES.md'].includes(name));
+async function bytes(url, maximum) {
+    const address = new URL(url);
+    if (address.protocol !== 'https:' || !['api.github.com', 'raw.githubusercontent.com'].includes(address.hostname) || address.username || address.password)
+        throw new Error('Invalid source transport URL');
+    const headers = { Accept: 'application/vnd.github+json', 'User-Agent': 'August-source-packages' };
+    // Only the API receives an explicitly supplied token. Raw downloads and
+    // redirects cannot carry it, and it never enters package metadata or logs.
+    if (address.hostname === 'api.github.com' && process.env.AUG_GITHUB_TOKEN)
+        headers.Authorization = 'Bearer ' + process.env.AUG_GITHUB_TOKEN;
+    const response = await fetch(address, { redirect: 'error', signal: AbortSignal.timeout(60000), headers });
+    if (!response.ok || !response.body)
+        throw new Error(`Cannot read public GitHub source (${response.status}). Check the repository/revision. For API rate limits, retry later or supply AUG_GITHUB_TOKEN for authenticated public reads.`);
+    if (Number(response.headers.get('content-length') ?? 0) > maximum)
+        throw new Error('GitHub source response exceeds its size limit');
+    const chunks = [];
+    let length = 0;
+    for await (const chunk of response.body) {
+        length += chunk.length;
+        if (length > maximum)
+            throw new Error('GitHub source response exceeds its size limit');
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+}
+/** Public GitHub snapshots use HTTPS objects, so consumers do not need Git or an SDK. */
+export async function materializeGitHub(request, destination, offline, locked) {
+    const reference = gitReference(request), url = new URL(reference.repository), parts = url.pathname.split('/').filter(Boolean), owner = parts[0], repo = parts[1]?.replace(/\.git$/, '');
+    if (url.hostname !== 'github.com' || parts.length !== 2 || !owner || !repo)
+        throw new Error('GitHub transport requires an owner/repository URL');
+    if (locked && (locked.repository !== reference.repository || locked.folder !== reference.folder || locked.revision !== reference.revision || !/^[0-9a-f]{40}$/.test(locked.commit)))
+        throw new Error('Invalid locked GitHub source identity');
+    const cache = resolve(process.env.AUG_PACKAGE_CACHE ?? join(homedir(), '.cache/augscript/packages'));
+    const base = join(cache, 'https-' + sourceAlias(reference.repository) + '-' + sourceAlias(reference.folder));
+    mkdirSync(base, { recursive: true });
+    return withPackageLockAsync(base + '.lock', async () => {
+        let commit = locked?.commit;
+        const revisionCache = join(base, 'revision-' + sourceAlias(reference.revision) + '.json');
+        if (!commit && offline && existsSync(revisionCache))
+            commit = JSON.parse(readFileSync(revisionCache, 'utf8')).commit;
+        if (!commit) {
+            if (offline)
+                throw new Error('GitHub revision is not cached. Run aug install online once: ' + request);
+            const value = JSON.parse((await bytes(`https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/commits/${encodeURIComponent(reference.revision)}`, 4 * 1024 * 1024)).toString());
+            commit = value.sha;
+            if (!/^[0-9a-f]{40}$/.test(commit))
+                throw new Error('GitHub did not resolve an exact commit');
+        }
+        if (!/^[0-9a-f]{40}$/.test(commit))
+            throw new Error('Invalid cached GitHub revision');
+        const snapshot = join(base, commit), metadata = join(base, commit + '.json');
+        if (!existsSync(snapshot) || !existsSync(metadata)) {
+            if (offline)
+                throw new Error('Locked GitHub source is not cached: ' + commit);
+            // An interrupted installation may leave either half of the cache entry.
+            // The exclusive writer discards that incomplete entry before retrying.
+            rmSync(snapshot, { recursive: true, force: true });
+            rmSync(metadata, { force: true });
+            const tree = JSON.parse((await bytes(`https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/git/trees/${commit}?recursive=1`, 16 * 1024 * 1024)).toString());
+            if (tree.truncated || !Array.isArray(tree.tree))
+                throw new Error('GitHub source tree coverage is incomplete; installation stopped');
+            const prefix = reference.folder ? reference.folder + '/' : '';
+            const entries = tree.tree.filter((e) => e.type === 'blob' && typeof e.path === 'string' && e.path.startsWith(prefix) && selected(e.path.slice(prefix.length)));
+            if (!entries.length || entries.length > 10000)
+                throw new Error('GitHub package has no source files or exceeds its file limit');
+            const stage = mkdtempSync(join(base, '.snapshot-'));
+            let total = 0;
+            const digests = {};
+            try {
+                // Bounded concurrency avoids one network round trip per source file.
+                for (let i = 0; i < entries.length; i += 8) {
+                    const batch = await Promise.allSettled(entries.slice(i, i + 8).map(async (entry) => {
+                        const name = entry.path.slice(prefix.length);
+                        if (!['100644', '100755'].includes(entry.mode) || name.includes('\\') || name.split('/').some((p) => !p || p === '.' || p === '..' || p.startsWith('.')) || !/^[0-9a-f]{40}$/.test(entry.sha))
+                            throw new Error('GitHub package source must be regular files inside its folder: ' + name);
+                        const content = await bytes(`https://raw.githubusercontent.com/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/${commit}/${entry.path.split('/').map(encodeURIComponent).join('/')}`, 32 * 1024 * 1024);
+                        total += content.length;
+                        if (total > 32 * 1024 * 1024)
+                            throw new Error('GitHub source package exceeds 32 MiB');
+                        const actual = createHash('sha1').update('blob ' + content.length + '\0').update(content).digest('hex');
+                        if (actual !== entry.sha)
+                            throw new Error('GitHub source blob identity differs from the resolved tree');
+                        digests[name] = createHash('sha256').update(content).digest('hex');
+                        mkdirSync(dirname(join(stage, name)), { recursive: true });
+                        writeFileSync(join(stage, name), content);
+                    }));
+                    const rejected = batch.find(r => r.status === 'rejected');
+                    if (rejected?.status === 'rejected')
+                        throw rejected.reason;
+                }
+                renameSync(stage, snapshot);
+                writeFileSync(metadata, JSON.stringify({ format: 1, commit, files: digests }));
+            }
+            finally {
+                rmSync(stage, { recursive: true, force: true });
+            }
+        }
+        const facts = JSON.parse(readFileSync(metadata, 'utf8'));
+        if (facts.format !== 1 || facts.commit !== commit || !facts.files)
+            throw new Error('Invalid cached GitHub source metadata');
+        const list = (folder, prefix = '') => readdirSync(folder, { withFileTypes: true }).flatMap(entry => {
+            if (entry.isSymbolicLink())
+                throw new Error('Cached GitHub source cannot contain symbolic links');
+            const path = prefix + entry.name;
+            return entry.isDirectory() ? list(join(folder, entry.name), path + '/') : entry.isFile() ? [path] : (() => { throw new Error('Cached GitHub source requires regular files'); })();
+        });
+        if (lstatSync(snapshot).isSymbolicLink() || JSON.stringify(list(snapshot).sort()) !== JSON.stringify(Object.keys(facts.files).sort()))
+            throw new Error('Cached GitHub source file set differs from the resolved snapshot');
+        for (const [name, digest] of Object.entries(facts.files)) {
+            if (name.includes('\\') || name.split('/').some(p => !p || p === '.' || p === '..' || p.startsWith('.')))
+                throw new Error('Cached source path escapes its snapshot');
+            if (createHash('sha256').update(readFileSync(join(snapshot, name))).digest('hex') !== digest)
+                throw new Error('Cached GitHub source changed: ' + name);
+        }
+        cpSync(snapshot, destination, { recursive: true });
+        writeFileSync(revisionCache, JSON.stringify({ commit }));
+        return { ...reference, commit: commit };
+    });
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url) && process.argv[2] === '--materialize') {
+    try {
+        const input = JSON.parse(process.argv[3]);
+        const result = await materializeGitHub(input.request, input.destination, input.offline, input.locked);
+        process.stdout.write(JSON.stringify(result));
+    }
+    catch (error) {
+        process.stderr.write((error instanceof Error ? error.message : String(error)) + '\n');
+        process.exitCode = 1;
+    }
+}

package/src/git-packages.js

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 import { withPackageLock } from "./package-locking.js";
 export const isGitSource = (value) => /^(?:https:\/\/|git\+(?:https|file):\/\/)/.test(value);
 export const sourceAlias = (value) => 'url_' + createHash('sha256').update(value).digest('hex').slice(0, 20);
@@ -65,6 +66,13 @@ export function materializeGit(request, destination, offline, locked) {
     if (locked && (locked.repository !== reference.repository || locked.folder !== reference.folder || locked.revision !== reference.revision ||
         !/^[a-f0-9]{40,64}$/.test(locked.commit)))
         throw new Error('Git package lock has an invalid repository, folder, or commit.');
+    if (new URL(reference.repository).hostname === 'github.com' && !process.env.AUG_GIT) {
+        const transport = new URL(import.meta.url.endsWith('.ts') ? './git-http.ts' : './git-http.js', import.meta.url);
+        const result = spawnSync(process.execPath, [fileURLToPath(transport), '--materialize', JSON.stringify({ request, destination, offline, locked })], { encoding: 'utf8', timeout: 180000, maxBuffer: 4 * 1024 * 1024 });
+        if (result.status !== 0)
+            throw new Error(result.stderr.trim() || result.error?.message || 'GitHub source installation failed');
+        return JSON.parse(result.stdout);
+    }
     const cache = resolve(process.env.AUG_PACKAGE_CACHE ?? join(homedir(), '.cache', 'augscript', 'packages'));
     const repository = join(cache, sourceAlias(reference.repository));
     mkdirSync(cache, { recursive: true });
@@ -91,7 +99,7 @@ export function materializeGit(request, destination, offline, locked) {
             if (!match || !match[3].startsWith(prefix))
                 continue;
             const file = match[3].slice(prefix.length);
-            if (!file.endsWith('.aug') && !['aug-package.json', 'package.json', 'main.yaml', 'README.md', 'LICENSE'].includes(file))
+            if (!file.endsWith('.aug') && !['aug-package.json', 'package.json', 'main.yaml', 'README.md', 'LICENSE', 'native.abi.json', 'THIRD_PARTY_NOTICES.md'].includes(file))
                 continue;
             if (!['100644', '100755'].includes(match[1]) || file.includes('\\') || file.split('/').some(part => !part || part === '..' || part.startsWith('.')))
                 throw new Error(`Git package source must be regular files inside its folder: ${file}`);

package/src/help.js

@@ -4,6 +4,7 @@ const type = (detail, documentation) => ({ detail, documentation, category: 'typ
 const fn = (detail, documentation) => ({ detail, documentation, category: 'function' });
 const operator = (detail, documentation) => ({ detail, documentation, category: 'operator' });
 export const languageHelp = {
+    resource: keyword('extern C resource Tensor', 'Declare an opaque native object with a descriptor-checked release operation. Store acquired objects in own bindings; their scope releases them exactly once. Resource declarations belong to native packages, outside main.aug.'),
     RequireLogin: { category: 'tag', detail: '[RequireLogin(authentication=auth)]', documentation: 'Verify credentials before typed body decoding. Map auth to an explicit resolve Authentication parameter and infer its authenticate operation. null produces 401; the adapter validates the credential. HTTP policies precede custom parameter interceptors.' },
     RequirePermission: { category: 'tag', detail: '[RequirePermission(authentication=auth, authorization=permissions, permission="users.read")]', documentation: 'Authenticate the request and authorize one literal permission before decoding. Both dependencies are explicit resolve parameters; declare their authenticate and authorize effects. Missing credentials produce 401 and a denied permission produces 403.' },
     LogRequest: { category: 'tag', detail: '[LogRequest(logger=logger)]', documentation: 'Map a resolve RequestLogger parameter and infer its complete operation. Observe the final status and monotonic duration after output finishes, or status 499 on disconnect. Layers complete in reverse written order.' },
@@ -46,7 +47,7 @@ export const languageHelp = {
     HttpRequest: type('HttpRequest', 'A request supplied through from request. Its method, path, headers and bounded body are explicit. form<T>() allows protocol-specific form errors.'),
     HttpResponse: type('HttpResponse<T>', 'A typed HTTP body with explicit status and headers. HttpResponse(body=value, status=201, headers=headers) constructs a response. Status literals range from 200 to 599; a dynamic status requires handling or declaring HttpError.'),
     record: keyword('record Point(int x, int y)', 'Declare deeply immutable data with labeled construction and structural equality/hashing. Records contain primitives, tuples and other records. An initialize block validates inputs; validation infers rejected inputs; an explicit unless ErrorType limits permitted failures.'),
-    initialize: keyword('initialize: ...', 'Run constructor work once after header inputs and local fields are initialized, before returning the class or record. Put this block inside the declaration, before class methods. Construction stays pure. Records can validate inputs and raise checked errors, but cannot replace immutable fields.'),
+    initialize: keyword('initialize: ...', 'Run constructor work once after header inputs and local fields are initialized, before returning the class or record. Put this block inside the declaration, before class methods. Construction stays pure. Classes declare checked constructor failures with unless before implements; failed construction releases transferred owned fields. Records can infer validation failures but cannot replace immutable fields.'),
     fixture: keyword('fixture example() returns Data: ...', 'Declare reusable test data through an ordinary checked function. Other files must import the fixture explicitly. Its dependencies and capabilities follow the same header contract rules as other functions.'),
     for: keyword('for item in items: ...', 'Traverse a List, Set, homogeneous Tuple, or Map. Map entries are tuples, so for (key, value) in map unpacks them. Iteration snapshots the collection in insertion order and gives elements read-only access.'),
     match: keyword('match value: when ...', 'Choose a checked case. Cover true and false for bool, null and some for nullable values, or add else. Concrete class cases narrow the named value. Duplicate and unreachable cases are rejected.'),
@@ -169,6 +170,13 @@ for (const operation of builtinFunctions)
         languageHelp[operation.name] = fn(`${operation.name}(${operation.parameters.map(param => `${param.label}=${param.type}`).join(', ')}) returns ${operation.returns}` +
             (operation.errors?.length ? ` unless ${operation.errors.join(' and ')}` : ''), operation.documentation);
 export const diagnosticHelp = {
+    NATIVE_HEADER: 'The native maintainer header does not match its reviewed ownership descriptor. Check fixed-width types, pointer constness, outputs, release signatures and the error record layout. aug bind header uses an explicitly selected Clang only; package consumers do not need Clang. Header checks do not prove allocator pairing, retention or thread promises.',
+    NATIVE_ABI: 'Keep the August declarations and native.abi.json in the same package. Parameter labels, types, resource ownership, checked errors and effects must match. Different packages cannot supply the same physical native symbol.',
+    NATIVE_INTEGRITY: 'The source or native archive differs from its pinned digest. Reinstall the exact package version or ask its maintainer to publish a new version. Installation never runs package build scripts.',
+    NATIVE_TARGET: 'This native package has no compatible prebuilt artifact for your OS, architecture, libc version or C++ runtime. LLVM builds target macOS 14+ ARM64 and Debian/Ubuntu GNU/Linux x86-64 or ARM64 with glibc 2.36+. Linux artifacts must declare their glibc floor. Musl and cross compilation are unsupported. Use one of the listed targets; missing artifacts do not trigger a source build.',
+    NATIVE_LOCK: 'Run aug install to record the verified source and native target. Commit aug.lock.json. Frozen builds reject changed selections; offline builds require an already verified cache.',
+    BACKEND_UNSUPPORTED: 'LLVM cannot compile this construct or legacy link setting. Use package-declared native bindings and link inputs. An explicit --backend c can compile migration fixtures without native ABI packages and requires a C toolchain. No automatic backend fallback occurs.',
+    IR_INVALID: 'The compiler produced execution IR that failed structural or ABI verification before LLVM emission. Report this source location and the compiler version. Source typing and ownership checks still run before lowering.',
     SYNTAX: 'Use word boolean operators, initialize blocks, optional Type, implement with, and resolve Key to name. The editor migration fix or aug migrate --write upgrades rejected legacy spellings while preserving grouping.',
     NATIVE: 'The C compiler reported an error at this August location. Check the external C declaration and main.yaml libraries/library_paths. Native commands prepare required pinned libraries automatically. Missing system tools include installation help. If valid August code fails without an external C boundary, report the compiler output and generated .aug-build/program.c.',
     CONFIG: 'main.yaml uses the documented scalar settings and list settings. Duplicate keys, unsupported values, and unknown lint rules are errors during check.',
@@ -191,7 +199,7 @@ export const diagnosticHelp = {
     TEST: 'Place the suite beside its declaration. Class tests initialize their named subject; test endpoint NAME client supplies an HTTP pipeline client. Put when bindings and setup before it cases and assert a bool in every case. Run aug test --group NAME to select a group.',
     HTTP: 'Declare endpoint inputs with from path/query/header/body/cookie/form/request and dependencies with resolve. Select endpoints in main with serve. HTTP policies use literal options and explicit capability mappings; put them before custom parameter interceptors.',
     JSON: 'Expose concrete immutable data records and collections. Decode<T>() requires a concrete JSON data type; freeze existing mutable collection aliases before storing them in a record.',
-    CONCURRENCY: 'Use scope for child-task lifetimes, start a labeled call, and wait for its result before mutating or moving any object the child captured. This includes writes inside an existing borrow block. A start inside a loop can create several children; use a scope inside the loop to join each iteration. Use Shared<T> and a short lock block for shared mutation; release the lock before I/O, waits, or starting tasks.',
+    CONCURRENCY: 'Use scope for child-task lifetimes, start a labeled call, and wait for its result before mutating or moving any object the child captured. This includes writes inside an existing borrow block. A task may consume owned inputs, but cannot return an owned value; release resources inside it and return immutable data. A start inside a loop can create several children; use a scope inside the loop to join each iteration. Use Shared<T> and a short lock block for shared mutation; release the lock before I/O, waits, or starting tasks.',
     INTERCEPTOR: 'Declare an interceptor with one around body. Map its selected inputs to target labels, preserve the target result and ownership, and supply constructor dependencies through resolve.',
     NEXT: 'Use next only inside around, with optional labeled overrides. Each execution path may call it at most once; loops and catch paths can repeat a call.',
     LEX: 'Check quotes, comment terminators, and supported characters.',

package/src/ir-types.js

@@ -0,0 +1,5 @@
+/** These cells can never retain a managed pointer after checked execution. */
+export function isIRScalar(type) {
+    return !type.nullable && !type.optional && !type.args.length &&
+        ['int', 'c_int', 'float', 'bool'].includes(type.name) && type.id === 'builtin:' + type.name;
+}