@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/src/git-packages.js

@@ -0,0 +1,118 @@
+import { createHash } from 'node:crypto';
+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);
+export const importSource = (parts) => (isGitSource(parts[0]) ? JSON.stringify(parts[0]) : parts[0]) + parts.slice(1).map(part => '.' + part).join('');
+/** A repository URL can select a tag and, on GitHub, a folder within the repository. */
+export function gitReference(request) {
+    try {
+        if (decodeURIComponent(request.split('#')[0]).split(/[\\/]/).some(part => part === '.' || part === '..'))
+            throw new Error('Repository URLs cannot contain path traversal.');
+    }
+    catch {
+        throw new Error('Invalid repository URL or path traversal.');
+    }
+    let url;
+    try {
+        url = new URL(request.replace(/^git\+/, ''));
+    }
+    catch {
+        throw new Error(`Invalid package repository URL: ${request}`);
+    }
+    if (!['https:', 'file:'].includes(url.protocol) || url.username || url.password || url.search ||
+        url.protocol === 'file:' && !request.startsWith('git+file:'))
+        throw new Error('Use a public HTTPS repository URL without credentials, or git+file:///PATH for a local Git repository.');
+    const revision = decodeURIComponent(url.hash.slice(1)) || 'HEAD';
+    url.hash = '';
+    let folder = '', ref = revision;
+    if (url.hostname === 'github.com') {
+        const parts = url.pathname.split('/').filter(Boolean).map(decodeURIComponent);
+        if (parts.length < 2)
+            throw new Error('A GitHub package URL needs an owner and repository.');
+        if (parts[2] === 'tree') {
+            if (!parts[3] || revision !== 'HEAD')
+                throw new Error('Choose the revision with /tree/TAG/FOLDER or #TAG, not both.');
+            ref = parts[3];
+            folder = parts.slice(4).join('/');
+        }
+        else
+            folder = parts.slice(2).join('/');
+        url.pathname = '/' + parts.slice(0, 2).join('/').replace(/\.git$/, '') + '.git';
+    }
+    if (!/^[A-Za-z0-9][A-Za-z0-9._/+-]*$/.test(ref) || ref.includes('..') || ref.endsWith('/'))
+        throw new Error('Package revision must be a commit, tag, or branch name.');
+    if (folder.split('/').some(part => part === '..' || part === '.' || part.startsWith('_')) || folder.includes('\\'))
+        throw new Error('Package folders must stay inside the repository and cannot be private.');
+    return { request, repository: url.href, revision: ref, folder };
+}
+function git(args, cwd) {
+    const result = spawnSync(process.env.AUG_GIT ?? 'git', ['-c', 'core.hooksPath=/dev/null', ...args], {
+        cwd, timeout: 120000, maxBuffer: 32 * 1024 * 1024, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }
+    });
+    if (result.error)
+        throw new Error(`Cannot read a Git package: ${result.error.message}. Install Git or set AUG_GIT to its executable.`);
+    if (result.status !== 0)
+        throw new Error(`Cannot read a Git package: ${result.stderr.toString().trim()}. Check the repository URL and revision; private repositories are outside this workflow.`);
+    return result.stdout;
+}
+/** Read source blobs without checking out files, executing hooks, or following repository symlinks. */
+export function materializeGit(request, destination, offline, locked) {
+    const reference = gitReference(request);
+    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 });
+    return withPackageLock(repository + '.lock', () => {
+        if (!existsSync(repository)) {
+            if (offline)
+                throw new Error(`Git package is not cached: ${request}. Run aug run online once before using --offline.`);
+            git(['init', '--bare', repository]);
+        }
+        let commit = locked?.commit;
+        const objectExists = commit && spawnSync(process.env.AUG_GIT ?? 'git', ['--git-dir', repository, 'cat-file', '-e', commit + '^{commit}']).status === 0;
+        if (!objectExists) {
+            if (offline)
+                throw new Error(`Git revision is not cached: ${commit ?? request}. Restore the package cache or run aug run online.`);
+            git(['--git-dir', repository, 'fetch', '--no-tags', '--depth=1', '--', reference.repository, commit ?? reference.revision]);
+            commit = git(['--git-dir', repository, 'rev-parse', 'FETCH_HEAD^{commit}']).toString().trim();
+        }
+        const result = { ...reference, commit: commit };
+        const prefix = reference.folder ? reference.folder + '/' : '';
+        const listing = git(['--git-dir', repository, 'ls-tree', '-rz', '--full-tree', result.commit, '--', prefix || '.']).toString();
+        let bytes = 0, count = 0;
+        for (const entry of listing.split('\0').filter(Boolean)) {
+            const match = /^(\d+) blob ([a-f0-9]+)\t([\s\S]+)$/.exec(entry);
+            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', '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}`);
+            const contents = git(['--git-dir', repository, 'cat-file', 'blob', match[2]]);
+            bytes += contents.length;
+            if (++count > 10000 || bytes > 32 * 1024 * 1024)
+                throw new Error('Git source package exceeds 10,000 files or 32 MiB.');
+            const path = join(destination, file);
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, contents);
+        }
+        if (!count)
+            throw new Error(`No August source at ${request}. Choose the folder containing export.aug or aug-package.json.`);
+        return result;
+    });
+}

package/src/help.js

@@ -4,9 +4,10 @@ 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 = {
-    RequireLogin: { category: 'tag', detail: '[RequireLogin(authentication=auth)]', documentation: 'Verify credentials before typed body decoding. Map auth to an explicit resolve Authentication parameter and declare uses auth.authenticate. null produces 401; the adapter validates the credential. HTTP policies precede custom parameter interceptors.' },
+    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 declare uses logger.complete. Observe the final status and monotonic duration after output finishes, or status 499 on disconnect. Layers complete in reverse written order.' },
+    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.' },
     RateLimit: { category: 'tag', detail: '[RateLimit(requests=100, seconds=60)]', documentation: 'A bounded per-endpoint, per-peer fixed-window request limit. Uses the transport peer address, never an untrusted forwarding header. Rejected requests return 429 before body decoding. The table has 2048 entries and rejects new identities when full.' },
     Timeout: { category: 'tag', detail: '[Timeout(milliseconds=5000)]', documentation: 'Bound the request and its streaming producer with a monotonic deadline. Before output, return 504. After headers, terminate the stream. Cancellation joins children and runs always cleanup; native C operations finish before cancellation can be observed.' },
     Cors: { category: 'tag', detail: '[Cors(origins=["https://example.test"], headers=["content-type"], credentials=true)]', documentation: 'Allow exact literal HTTP(S) origins and explicit request header names. OPTIONS preflight checks the selected method and headers. Wildcard origins cannot use credentials. Valid responses include CORS and Vary headers; disallowed origins return 403.' },
@@ -38,15 +39,15 @@ export const languageHelp = {
     Task: type('Task<T>', 'A child computation owned by a scope. wait for reads its result; the scope joins children before releasing dependencies.'),
     Shared: type('Shared<T>', 'Synchronized mutable state. Construction takes a fresh or owned value. Read and mutate the value only through lock shared as state. A child borrowing an owned Shared<T> pins the wrapper until it finishes; the parent cannot move it into another owner while the child uses it.'),
     Bytes: type('Bytes', 'Immutable length-aware binary data. text() validates UTF-8; base64url() emits canonical unpadded URL-safe base64.'),
-    Json: type('Json', 'Immutable JSON data. Parse with august.json, decode concrete records with decode<T>(), and stringify with lossless integer handling.'),
+    Json: type('Json', 'Immutable JSON data. Import parse from the JSON source package, decode concrete records with decode<T>(), and stringify with lossless integer handling.'),
     Html: type('Html', 'Checked server markup produced with JSX elements and components. Interpolated text and attributes are escaped automatically.'),
     HttpAction: type('HttpAction', 'An immutable deferred HTTP call created with handle endpoint(...). Bind it to a form onSubmit or button onClick. The browser sends the request; endpoint dependencies and application logic run on the server.'),
     ServerEvent: type('ServerEvent<T>', 'One SSE event containing concrete JSON data, plus optional id, event, and retry milliseconds. CR, LF and NUL are rejected in metadata. The endpoint streams ServerEvent<T> and yields each event under transport backpressure.'),
     Headers: type('Headers', 'Immutable HTTP fields. with adds a checked field; get and all read case-insensitively. Duplicate Set-Cookie values remain separate.'),
     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; declare rejected inputs with unless ErrorType.'),
-    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 declared unless errors, but cannot replace immutable fields.'),
+    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. 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.'),
@@ -57,14 +58,14 @@ export const languageHelp = {
     scope: keyword('scope: ...', 'Create a local DI and child-task lifetime. Children join before dependencies are reclaimed; unhandled failures cancel siblings. Scoped references cannot escape. Nested scopes have independent caches.'),
     composition: keyword('composition Services: implement Logger with Adapter', 'Group static bindings behind an explicitly imported module declaration. Include the composition in main before executable statements; its own file must import every referenced contract and implementation.'),
     include: keyword('include Services', 'Expand an explicitly imported composition into the application root. Duplicate bindings and dependency cycles are checked after all includes are collected.'),
-    IndexError: type('IndexError implements Error', 'Checked failure for an invalid List.get position. Catch it, declare unless IndexError, or use List.at for a nullable lookup.'),
+    IndexError: type('IndexError implements Error', 'Checked failure for an invalid List.get position. Catch it or let it propagate. List.at returns a value or null instead.'),
     ArithmeticError: type('ArithmeticError implements Error', 'Checked failure for division by zero. int arithmetic otherwise wraps in the signed 64-bit range.'),
-    ConversionError: type('ConversionError implements Error', 'Checked failure when c_int(value=number) cannot fit the signed 32-bit C int range. Catch it or declare unless ConversionError.'),
+    ConversionError: type('ConversionError implements Error', 'Checked failure when c_int(value=number) cannot fit the signed 32-bit C int range. Catch it or let it propagate.'),
     c_int: type('c_int', 'Signed 32-bit C int. Convert explicitly with c_int(value=number), which raises ConversionError on overflow. It widens to int without loss. AugScript int maps to int64_t at the C boundary.'),
     interceptor: keyword('interceptor Name<T>(resolve Dependency dependency) { around(...) returns T { ... } }', 'Declare a reusable wrapper for functions, methods, or class construction. Apply it with `[Name]` or `[Name(y=x)]`. Inputs match target labels automatically; explicit mappings rename them. Tags enter in written order and results unwind in reverse. Each layer creates a fresh instance; dependencies are forwarded from the target header. Effective contracts include every layer\u2019s changes, capabilities, errors, and dependencies. Generic types are inferred from the target. Interceptors follow normal imports, exports, and underscore privacy.'),
-    around: fn('around(Type input) returns Type { return next(); }', 'The required entry point of an interceptor. Its parameters select target arguments, and its result must fit the target return type. Omit `returns` for void. It may validate, override mapped arguments, inspect the result, throw a checked error, or return early. Declare generic parameters on the interceptor header. Helper methods can be declared alongside around.'),
+    around: fn('around(Type input) returns Type { return next(); }', 'The required entry point of an interceptor. Its parameters select target arguments, and its result must fit the target return type. A forwarding body can omit returns and inherit the target result. It may validate, override mapped arguments, inspect the result, throw a checked error, or return early. Declare generic parameters on the interceptor header. Helper methods can be declared alongside around.'),
     next: fn('next(mappedLabel=value) returns TargetResult', 'Continue to the next interceptor layer or the original function/constructor. Available only inside an interceptor around body. `next()` forwards original arguments unchanged; optional labeled overrides use the interceptor parameter names and map back to the target. Unselected arguments are forwarded automatically. The compiler requires at most one next call on each execution path. Target errors propagate through the chain; additional errors declared by around become checked errors of the tagged callable.'),
-    import: keyword('import Logger and ConsoleLogger from logging', 'Bring public declarations into this file. Use `and` for several names, or `import everything from logging` for all public sibling declarations or folder exports. Imported dependencies are never re-exported implicitly. Names or modules starting with `_` stay private. A sibling module uses its filename without `.aug`; a folder exposes only names listed in `export.aug`.'),
+    import: keyword('import Logger and ConsoleLogger from logging', 'Bring public declarations into this file. Use `and` for several names, or `import everything from logging` for all public sibling declarations or folder exports. Imported dependencies are never re-exported implicitly. Names or modules starting with `_` stay private. A sibling module uses its filename without `.aug`; a folder exposes only names listed in `export.aug`. A quoted public repository URL declares a source dependency; `aug run` installs it and locks its commit. Use `aug add URL --as NAME` for a shorter import alias.'),
     and: keyword('left and right', 'Logical AND on bool values. Skip the right operand when the left operand is false. Also join named imports, checked errors, contracts, and grouped task waits. Comparisons and not bind before and; and binds before or.'),
     or: keyword('left or right', 'Logical OR on bool values. Skip the right operand when the left operand is true. This is the lowest-precedence boolean operator. Symbolic || is rejected.'),
     not: keyword('not count == 0', 'Negate a bool expression. Comparisons bind before not, so not count == 0 means not (count == 0). not binds before and and or. Use parentheses to negate only one comparison operand. Symbolic ! is rejected; != remains inequality.'),
@@ -75,10 +76,10 @@ export const languageHelp = {
     pass: keyword('pass', 'An empty body. Use it inside an indented interface, class, function, or statement block. It performs no operation. Empty braced blocks may use {} instead.'),
     in: keyword('interface Consumer<in T>', 'Declare a contravariant interface type parameter. It may occur only in checked input positions. User-defined types are otherwise invariant. The same word is used by for iteration.'),
     out: keyword('interface Producer<out T>', 'Declare a covariant interface type parameter. It may occur only in checked output positions. Mutable containers are invariant; classes and interceptors cannot declare variance.'),
-    changes: keyword('increment() changes self', 'Declare observable mutation of self or a borrowed input. Callers must provide mutable access. Ordinary functions and methods are pure by default; changing a local variable or a fresh local object does not change caller-owned state.'),
-    uses: keyword('save(resolve FileWriter files, string path) uses files.write unless FileError', 'Declare the external capability operations this callable may use. Interfaces, public standalone functions, default methods and interceptor around methods keep explicit contracts. Class implementations and private helpers infer uses when omitted; hover, explain and API docs show the result. An explicit uses clause remains an upper bound. Effects are checked through calls and interceptor layers; implementations cannot exceed their interface contract. changes and unless remain explicit, and construction stays pure.'),
-    mutable: keyword('Counter(mutable int initial to _count)', 'Declare mutable class storage. Header fields are otherwise read-only after construction. An explicit public argument label can initialize private storage with Type label to _field. Mutating methods declare changes self and callers provide mutable access.'),
-    capability: keyword('capability Console { write(string value) uses Console.write }', 'Declare an interface for an external effect. Import the standard Console, FileReader, FileWriter and Arguments contracts from august.io, select adapters in main, and receive them through resolve parameters. Operations remain visible in uses clauses and can be replaced in tests.'),
+    changes: keyword('increment() changes self', 'Describe observable mutation of self or a borrowed input. Bodies infer changes when omitted; callers still need mutable access. Bodyless interface contracts declare permitted mutation. Local variables and fresh local objects do not change caller-owned state. An explicit clause limits the body.'),
+    uses: keyword('save(resolve FileWriter files, string path)', 'Bodies infer external capability operations when uses is omitted, including public functions, default methods and interceptor around methods. The editor shows non-editable inline hints; hover, explain, API docs and compiled specs expose checked contracts. Bodyless interfaces and extern declarations keep explicit contracts. An explicit uses clause remains an upper bound. Implementations cannot exceed their interface contract; construction and cleanup stay pure.'),
+    mutable: keyword('Counter(mutable int initial to _count)', 'Declare mutable class storage. Header fields are otherwise read-only after construction. An explicit public argument label can initialize private storage with Type label to _field. Bodies infer changes self; callers provide mutable access.'),
+    capability: keyword('capability Console { write(string value) uses Console.write }', 'Declare an interface for an external effect. Import the standard Console, FileReader, FileWriter and Arguments contracts from august.io, select adapters in main, and receive them through resolve parameters. Operations stay visible in inferred hints, hover and specs and can be replaced in tests.'),
     from: keyword('import Name from module;', 'Names the source of an import or export. Dotted paths cross folders; each crossed folder must expose the next one with `export folder child;`. A module starting with `_` is private.'),
     export: keyword('export Name from sibling;', 'Expose a public sibling declaration to other folders. Names, modules, and folders starting with `_` are private and cannot be exported. Export declarations belong only in `export.aug`.\n\n```aug\nexport Logger from logger;\n```'),
     folder: keyword('export folder child;', 'Expose a public child folder through the current folder’s `export.aug`. A folder starting with `_` cannot be exported.'),
@@ -91,12 +92,12 @@ export const languageHelp = {
     interface: keyword('interface Name extends Parent { ... }', 'Declare a contract. Interfaces may extend several interfaces and may provide default method bodies. A class must implement every method without a default. Method signatures start with their name, for example `log(string message);`.'),
     implements: keyword('Name() implements Interface { ... }', 'Marks a declaration as a class and lists the interfaces it satisfies. Every class needs at least one interface. Method signatures must match. Conflicting default implementations require an override. Put constructor work in an initialize block inside the class.'),
     extends: keyword('interface Child extends Parent, Other { ... }', 'Inherit methods from one or more interfaces. Class inheritance is not supported.'),
-    function: keyword('No function keyword', 'Functions and methods start with their name: `greet(string name) { ... }` or `greet(string name) returns string;`. Remove the old `function` prefix. Parameters use `Type name` order and callers use labels. Omit `returns` for a `void` result.'),
-    returns: keyword('name() returns Type', 'Specify a function or method return type. Without this clause, the result is `void`; the body may end without `return` or use `return;`. Returning a value requires a declared return type. `returns own Type` transfers ownership to the caller.'),
+    function: keyword('No function keyword', 'Functions and methods start with their name: greet(string name) { ... }. Remove the old function prefix. Parameters use Type name order and callers use labels. Bodies infer omitted returns, changes, uses and unless clauses; declarations without a body keep explicit contracts.'),
+    returns: keyword('name() returns Type', 'Bodies infer their result from return expressions or their implemented interface when this clause is omitted. No returned value means void. Bodyless signatures still need non-void result types. Explicit result types are checked assertions; returns own Type explicitly transfers ownership. Recursive or ambiguous results may require a type anchor.'),
     return: keyword('return expression;', 'Finish the current function or method and give its result to the caller. A `void` function can use `return;`.'),
-    unless: keyword('load(bool fail) returns string unless FileError', 'Declare checked failures a function may raise instead of returning its result. Callers must catch the failures or declare them with unless too. Separate several types with `and` or commas; `unless Error` accepts any error type. The statement that raises an error remains `throw`.'),
+    unless: keyword('load(bool fail) unless FileError', 'Describe checked failures that escape a call. Bodies infer uncaught errors when unless is omitted; catch blocks remove handled errors. Main must handle escaping errors. Bodyless interfaces declare permitted failures. Explicit unless remains an upper bound; unless Error accepts any error type. Record validation can infer its failures too.'),
     throws: keyword('Use unless', 'This old error-contract spelling is rejected. Replace `throws FileError` with `unless FileError`. Javadoc `@throws` remains supported.'),
-    throw: keyword('throw error;', 'Raise a value whose class implements `Error`. The enclosing function must declare the error or the call must be handled by a matching `catch`.'),
+    throw: keyword('throw error;', 'Raise a value whose class implements `Error`. An executable body infers uncaught errors; main must handle them with a matching catch.'),
     try: keyword('try { ... } catch Error error { ... }', 'Run statements that may throw checked errors. Add a `catch` for each error, or use `catch Error` for any throwable error.'),
     catch: keyword('catch Error error { ... }', 'Handle a thrown error from the preceding `try` block. The caught value is available under the name after its type.'),
     if: keyword('if condition: ...', 'Run a block when its condition is bool. Use braces or a trailing colon and an indented body. Tabs or spaces are accepted; mixed indentation prefixes are rejected.'),
@@ -105,7 +106,7 @@ export const languageHelp = {
     own: keyword('own Type name to expression;', 'Give a value exclusive ownership and deterministic cleanup at scope exit. Owned values cannot be copied; they can move into `own` parameters, fields, or returns. `=` is also accepted.\n\n```aug\nown Resource resource to Resource();\n```'),
     borrow: keyword('borrow value { ... }', 'Take exclusive mutable access for the duration of this block. Ordinary reads need no borrow. Managed List, Set, and Map mutations require one. Starting a child that reads the value suspends this mutation right until wait for the child.\n\n```aug\nborrow items { items.append(value=1) }\n```'),
     unsafe: keyword('unsafe { ... }', 'Permit calls to declared `extern C` functions within this block. The compiler does not verify the safety of foreign code.'),
-    extern: keyword('extern C name(Type arg) returns Type', 'Declare a C function. Calls require unsafe and external callables declare uses C.name. int maps to int64_t, c_int to signed 32-bit int, float to double, bool to C bool, and string to a temporary UTF-8 const char pointer. Foreign code must respect the declared ABI and cannot retain managed pointers.'),
+    extern: keyword('extern C name(Type arg) returns Type', 'Declare a C function. Calls require unsafe and executable callers infer uses C.name. int maps to int64_t, c_int to signed 32-bit int, float to double, bool to C bool, and string to a temporary UTF-8 const char pointer. Foreign code must respect the declared ABI and cannot retain managed pointers.'),
     C: keyword('extern C name(...);', 'Selects C as the foreign function interface for an `extern` declaration.'),
     true: keyword('true', 'Boolean true. Conditions and logical operators require `bool`.'),
     false: keyword('false', 'Boolean false. and and or evaluate the right side only when needed. Conditions require bool values.'),
@@ -116,7 +117,7 @@ export const languageHelp = {
     string: type('string', 'Immutable valid Unicode encoded as UTF-8, without embedded NUL. Invalid literals are compile errors and invalid text files raise FileError. The + operator joins strings. C string pointers live only for the unsafe call.'),
     void: type('void', 'No return value. A function can omit `returns void`.'),
     Error: type('Error', 'Root throwable interface. User defined error classes implement `Error`; `catch Error` handles any throwable type.'),
-    FileError: type('FileError', 'Built in checked error from text file operations. Catch it or declare `unless FileError`.'),
+    FileError: type('FileError', 'Checked failure from text file operations. Catch it or let it propagate.'),
     List: type('List<T>', 'Ordered collection: `[1, 2]` infers List<int>. A typed declaration supplies empty or nested literal types: `List<int> numbers = []`. `List<T>(...)` also accepts positional elements. `append(value=...)` requires mutable access; `get(index=...)` reads; `length()` returns its size.'),
     Set: type('Set<T>', 'Hash set of unique values: `{1, 2, 1}` infers Set<int> with two items. Use `Set<int> numbers = {}` or `Set<int>()` for an empty set. `add(value=...)` requires mutable access; `contains(value=...)` and `length()` read. Primitive values and immutable tuples use value equality; other objects use identity.'),
     Tuple: type('Tuple<T1, T2, ...>', 'Fixed immutable positions: `(1, 2)` infers Tuple<int, int>, `(1, "apple")` infers Tuple<int, string>. `(1)` is grouping, `(1,)` is a singleton tuple, and `()` is empty. `get(index=0)` requires a constant index so its result type is known. `length()` reads its size. Tuples compare by their items; contained objects remain managed references.'),
@@ -169,10 +170,17 @@ 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 native C toolchain reported an error at this AugScript source location. Check the external C declaration, linker configuration, and generated .aug-build/program.c; debug builds retain source line mapping.',
+    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.',
-    PACKAGE: 'Declare an import alias in main.yaml packages (or aug-package.json dependencies for a library), then run aug install. Commit aug.lock.json; use --frozen in CI. Imports cross only export.aug boundaries. Installed sources and compiler versions must match the lock; build/check never fetch packages.',
+    PACKAGE: 'Import directly from a quoted public repository URL, or use aug add URL --as NAME to declare an alias in main.yaml. aug run prepares declared application packages; aug install prepares them explicitly. Commit aug.lock.json and use aug install --frozen in CI. Changed installed sources require an explicit reinstall. Imports cross only export.aug boundaries. Installed sources and compiler versions must match the lock; build/check never fetch source packages.',
     MODULE: 'Keep imports acyclic and follow main.yaml module_dependencies. strict_modules also requires sibling public imports to appear in export.aug.',
     LINT: 'Optional project policies point out hidden dependencies, discarded errors, and growing public surfaces. Enable individual rules in main.yaml lint.',
     DOC: 'Javadoc @param names use public input labels. @return requires a value-returning callable; @throws names an unless error. Enable public_docs for missing-documentation warnings.',
@@ -182,15 +190,16 @@ export const diagnosticHelp = {
     ITERATION: 'for traverses a List, Set, Map, or homogeneous Tuple. Use tuple destructuring for map entries and heterogeneous tuples.',
     NUMBER: 'int is signed 64-bit with defined wrapping arithmetic. Integer literal spelling is exact. Float literals must be finite.',
     TEXT: 'Strings contain valid Unicode encoded as UTF-8, without NUL. Binary data needs an explicit unsafe adapter.',
-    EFFECT: 'Public function and interface contracts explicitly declare uses capability.operation. Implementations and private helpers infer omitted uses, while explicit clauses remain upper bounds. Declare changes for mutation and unless for errors. Receive dependencies in resolve header parameters; constructors and cleanup remain pure. Inferred effects cannot exceed an implemented interface or hold a lock during I/O.',
-    MUTABILITY: 'Class storage is read-only after construction unless marked mutable. Managed function inputs grant reading; use a borrow parameter and a changes contract to mutate them. Public read-only fields do not grant mutable access through aliases.',
+    EFFECT: 'Bodies infer capability use and mutation. Bodyless interfaces declare permitted effects; explicit clauses remain upper bounds. Receive dependencies in resolve header parameters. Inferred effects cannot exceed an implemented interface, grant mutation of managed inputs, add constructor I/O, or hold a lock during I/O.',
+    INFERENCE: 'Add a result or effect type anchor when recursion has no evidence or keeps expanding generic types. Bodies infer omitted contracts; bodyless and foreign declarations describe them explicitly.',
+    MUTABILITY: 'Class storage is read-only after construction unless marked mutable. Managed function inputs grant reading; use a borrow parameter to mutate them; bodies infer the changes contract. Public read-only fields do not grant mutable access through aliases.',
     GENERIC: 'Type arguments must be concrete at a call and consistent across labeled inputs. Mutable and user-defined types are invariant by default. Supply explicit type arguments when inputs do not determine them.',
     INDENT: 'Put the body after a trailing colon on the next line. Indent beyond its header, keep each block level consistent, and use tabs or spaces without mixing them in a prefix. Dedent to an enclosing level; use pass for an empty body.',
     COLLECTION: 'Use compatible item types or a declared collection type. Empty [] and {} need a contextual type. A tuple may contain different types; tuple.get needs a constant index.',
     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/http-contracts.js

@@ -0,0 +1,14 @@
+import { parse } from "./parser.js";
+// These declarations describe the native policy ABI. Package names do not determine compatibility.
+// Keep this schema aligned with the capabilities exported by the web library.
+const source = `record Principal(string subject, List<string> permissions)
+capability Authentication:
+    authenticate(HttpRequest request) returns optional Principal uses Authentication.authenticate unless HttpError
+capability Authorization:
+    authorize(Principal identity, string permission) returns bool uses Authorization.authorize unless HttpError
+capability RequestLogger:
+    complete(string method, string path, int status, int milliseconds) uses RequestLogger.complete
+`;
+export const nativeHttpContracts = new Map(parse('<native-http-contracts>', source).file.items
+    .filter(item => item.kind === 'interface' || item.kind === 'class')
+    .map(item => [item.name, item]));

package/src/http-policies.js

@@ -10,10 +10,10 @@ export const httpPolicyOptions = {
     Cors: { origins: 'strings', headers: 'optional strings', credentials: 'optional bool' }, Compress: {},
 };
 export const httpPolicyOptionHelp = {
-    authentication: 'Map an explicit resolve Authentication input. Declare uses input.authenticate. Missing identity returns 401 before wire decoding.',
-    authorization: 'Map an explicit resolve Authorization input. Declare uses input.authorize. Denied permission returns 403.',
+    authentication: 'Map an explicit resolve Authentication input. The compiler infers input.authenticate. Missing identity returns 401 before wire decoding.',
+    authorization: 'Map an explicit resolve Authorization input. The compiler infers input.authorize. Denied permission returns 403.',
     permission: 'Literal nonempty permission checked by the authorization adapter.',
-    logger: 'Map an explicit resolve RequestLogger input. Declare uses input.complete. The logger runs after completion or disconnect; put LogRequest first to observe rejected requests.',
+    logger: 'Map an explicit resolve RequestLogger input. The compiler infers input.complete. The logger runs after completion or disconnect; put LogRequest first to observe rejected requests.',
     requests: 'Literal request count per trusted transport peer and endpoint, from 1 to 1000000. Excess returns 429.',
     seconds: 'Literal fixed-window duration, from 1 to 86400 seconds.',
     milliseconds: 'Literal deadline from 1 to 3600000 milliseconds, covering handler, child tasks and response transport. Before output it returns 504; after output it closes the stream.',
@@ -44,10 +44,10 @@ export function checkHttpPolicy(annotation, fn, diagnostics, canonical) {
             if (entry.value || !param?.injected || param.type.name !== type || param.type.nullable || param.type.optional)
                 report(`${name}.${entry.name} maps an explicit resolve ${type} endpoint parameter`);
             else if (!canonical(param, type))
-                report(`${name}.${entry.name} requires the august.web ${type} capability`);
+                report(`${name}.${entry.name} requires a compatible ${type} capability from the web library`);
             else {
                 dependencies[Object.keys(specs[name]).filter(key => specs[name][key].startsWith('dependency:')).indexOf(entry.name)] = index;
-                if (!fn.uses?.some(effect => effect.source === param.name && effect.operation === operation))
+                if (fn.uses?.length && !fn.uses.some(effect => effect.source === param.name && effect.operation === operation))
                     report(`Declare uses ${param.name}.${operation} for ${name}`);
             }
             continue;

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;
+}