@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/src/policies.js

@@ -85,11 +85,11 @@ export function projectPolicies(project) {
                     if (!params.some(param => (param.label ?? param.name) === label))
                         report(node.span, `@param ${label} does not name a public input of ${node.name}`, 'DOC');
                 for (const tag of doc.tags ?? []) {
-                    if (['return', 'returns'].includes(tag.name) && !('returns' in node && node.returns.name !== 'void'))
+                    if (node.kind !== 'function' && ['return', 'returns'].includes(tag.name))
                         report(node.span, `@${tag.name} requires a value-returning callable`, 'DOC');
-                    if (['throws', 'exception'].includes(tag.name)) {
+                    if (node.kind !== 'function' && !(node.kind === 'class' && node.record && node.validationDeclared === false) && ['throws', 'exception'].includes(tag.name)) {
                         const name = tag.value.split(/\s/)[0];
-                        const errors = 'throws' in node ? node.throws : 'validationErrors' in node ? node.validationErrors ?? [] : [];
+                        const errors = node.kind === 'class' ? node.validationErrors ?? [] : [];
                         if (!('annotations' in node && node.annotations?.length) && !errors.some(error => error.name === name))
                             report(node.span, `@${tag.name} ${name} is absent from ${node.name}'s unless contract`, 'DOC');
                     }

package/src/project-init.js

@@ -1,18 +1,92 @@
 import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
+export const agentInstructions = `# Working on this August project
+
+Start in main.aug. It shows the imports, dependency bindings, and application startup.
+Read the adjacent .aug.md specification before changing a source file. Generate missing
+or stale explanations with aug spec; they describe checked behavior and link dependencies.
+
+Keep tests in the file that declares the behavior. Run aug check, aug test, and aug spec
+after a change, and use aug run to compile and run the application. Run prepares required
+source packages and native libraries. Commit aug.lock.json; do not edit .aug-packages.
+
+Use labeled inputs, narrow export.aug files, and underscore-prefixed private helpers.
+Leave return types, effects, and errors to inference when an executable body provides
+the answer. Bodyless interfaces still declare their contracts. Use borrow for mutation,
+and keep unsafe native calls inside small adapters. Explain intent in Javadoc when it
+is not evident from the code. Follow the existing indentation or brace style.
+
+Language guide: https://greenpandastudios.github.io/augscript/
+`;
+export const weatherSource = `/** The JSON shape returned by the forecast endpoint. Temperatures use whole degrees. */
+record WeatherForecast(string date, int temperatureC, int temperatureF, string summary)
+
+/** Return five simulated forecasts. Fixed data keeps the example and its tests reproducible. */
+endpoint GET "/weatherforecast" as weatherForecast():
+    return [
+        WeatherForecast(
+            date="2026-01-01",
+            temperatureC=0,
+            temperatureF=32,
+            summary="Freezing"
+        ),
+        WeatherForecast(
+            date="2026-01-02",
+            temperatureC=10,
+            temperatureF=50,
+            summary="Cool"
+        ),
+        WeatherForecast(
+            date="2026-01-03",
+            temperatureC=20,
+            temperatureF=68,
+            summary="Mild"
+        ),
+        WeatherForecast(
+            date="2026-01-04",
+            temperatureC=30,
+            temperatureF=86,
+            summary="Warm"
+        ),
+        WeatherForecast(
+            date="2026-01-05",
+            temperatureC=35,
+            temperatureF=95,
+            summary="Hot"
+        )
+    ]
+
+test endpoint weatherForecast client:
+    when forecasts:
+        it returns_json:
+            response = client.request(method="GET", path="/weatherforecast")
+            assert(condition=response.status == 200)
+        it rejects_other_methods:
+            response = client.request(method="POST", path="/weatherforecast")
+            assert(condition=response.status == 405)
+`;
 /** Create a small, runnable application without replacing existing files. */
-export function initProject(destination) {
+export function initProject(destination, template = 'hello') {
     const root = resolve(destination);
     if (existsSync(root) && readdirSync(root).length)
         throw new Error(`Directory is not empty: ${root}`);
     const name = basename(root);
     mkdirSync(root, { recursive: true });
     const files = {
+        'AGENTS.md': agentInstructions,
         'main.aug': `import Greeter and SimpleGreeter from greeting\n\nimplement Greeter with SimpleGreeter\nresolve Greeter to greeter\nprint(value=greeter.greet(name="August"))\n`,
-        'greeting.aug': `/** Build a greeting for a named person. */\ninterface Greeter:\n    /** Return a greeting for the named person. */\n    greet(string name) returns string\n\n/** A plain-language greeting. */\nSimpleGreeter() implements Greeter:\n    greet(string name) returns string:\n        return "Hello, " + name + "!"\n\ntest SimpleGreeter greeter:\n    when greetings:\n        greeter = SimpleGreeter()\n        it greets_a_person:\n            assert(greeter.greet(name="August") == "Hello, August!")\n`,
-        '.gitignore': '.aug-build/\n.aug-spec/\n*.aug.md\n',
-        'README.md': `# ${name}\n\nThis is an August application. Start in \`main.aug\`; its dependencies and startup are visible there.\n\n\`greeting.aug\` contains a public interface, its implementation, and a same-file test.\n\n\`\`\`sh\naug check .\naug test .\naug spec .\naug run .\n\`\`\`\n\nFor the language guide, see https://GreenPandaStudios.github.io/augscript/getting-started.\n`,
+        'greeting.aug': `/** Build a greeting for a named person. */\ninterface Greeter:\n    /** Return a greeting for the named person. */\n    greet(string name) returns string\n\n/** A plain-language greeting. */\nSimpleGreeter() implements Greeter:\n    greet(string name):\n        return "Hello, " + name + "!"\n\ntest SimpleGreeter greeter:\n    when greetings:\n        greeter = SimpleGreeter()\n        it greets_a_person:\n            assert(greeter.greet(name="August") == "Hello, August!")\n`,
+        '.gitignore': '.aug-build/\n.aug-spec/\n.aug-packages/\n.aug-install-*/\n*.aug.md\n',
+        'README.md': `# ${name}\n\nThis is an August application. Start in \`main.aug\`; its dependencies and startup are visible there.\n\n\`greeting.aug\` contains a public interface, its implementation, and a same-file test.\n\n\`\`\`sh\naug run\naug check\naug test\naug spec\n\`\`\`\n\nFor the language guide, see https://GreenPandaStudios.github.io/augscript/getting-started.\n`,
     };
+    if (template === 'weather') {
+        delete files['greeting.aug'];
+        files['main.aug'] = 'import weatherForecast from forecasts\n\nserve weatherForecast on port 8787\n';
+        files['forecasts.aug'] = weatherSource;
+        files['weather.http'] = '### Five simulated forecasts\nGET http://127.0.0.1:8787/weatherforecast\n\n### Generated OpenAPI document\nGET http://127.0.0.1:8787/openapi.json\n';
+        files['main.yaml'] = 'block_style: indent\nopenapi:\n  enabled: true\n  title: "Weather forecast API"\n  version: "0.1.0"\n';
+        files['README.md'] = `# ${name}\n\nA simulated weather API in August. Its endpoint, JSON record, and tests live in forecasts.aug.\n\nRun the server:\n\n\`\`\`sh\naug run\n\`\`\`\n\nOpen http://127.0.0.1:8787/weatherforecast for five forecasts, or http://127.0.0.1:8787/docs for the OpenAPI viewer. These are fixed examples, not live weather observations.\n\n\`\`\`sh\ncurl http://127.0.0.1:8787/weatherforecast\naug test\naug spec\n\`\`\`\n\nGuide: https://greenpandastudios.github.io/augscript/weather-api\n`;
+    }
     for (const [file, contents] of Object.entries(files))
         writeFileSync(join(root, file), contents, { flag: 'wx' });
     return root;

package/src/project.js

@@ -5,7 +5,8 @@ import { loadConfig } from "./config.js";
 import { projectPolicies } from "./policies.js";
 import { builtinFunctions, builtinTypes } from "./builtins.js";
 import { libraryChild, libraryRelative, standardLibraries } from "./libraries.js";
-import { projectPackages, readPackage, sourcePaths } from "./package-manager.js";
+import { packageSpecifications, projectPackages, readPackage, sourcePaths } from "./package-manager.js";
+import { isGitSource, sourceAlias } from "./git-packages.js";
 export function isPrivateName(name) { return name.startsWith('_'); }
 function diagnostic(file, line, column, message, code) {
     return { file, line, column, message, code };
@@ -35,7 +36,7 @@ export function loadProject(projectRoot, overrides = new Map(), cache) {
     const { config, diagnostics } = loadConfig(root);
     let library;
     let sourceRoot = root;
-    if (existsSync(join(root, 'aug-package.json'))) {
+    if (existsSync(join(root, 'aug-package.json')) || !existsSync(join(root, 'main.aug')) && (existsSync(join(root, 'export.aug')) || existsSync(join(root, 'src/export.aug')))) {
         try {
             const loaded = readPackage(root);
             library = loaded.manifest;
@@ -45,7 +46,7 @@ export function loadProject(projectRoot, overrides = new Map(), cache) {
             diagnostics.push(diagnostic(join(root, 'aug-package.json'), 1, 1, error.message, 'PACKAGE'));
         }
     }
-    const packages = projectPackages(root, library?.dependencies ?? config.packages, sourceRoot);
+    const packages = projectPackages(root, packageSpecifications(sourceRoot, library?.dependencies ?? config.packages, overrides), sourceRoot);
     diagnostics.push(...packages.diagnostics);
     const read = (path) => {
         const source = overrides.get(path) ?? readFileSync(path, 'utf8');
@@ -56,7 +57,7 @@ export function loadProject(projectRoot, overrides = new Map(), cache) {
         cache?.set(path, parsed);
         return parsed;
     };
-    for (const path of new Set([...sourceFiles(sourceRoot), ...overrides.keys()].filter(path => path.endsWith('.aug')))) {
+    for (const path of new Set([...sourceFiles(sourceRoot), ...[...overrides.keys()].filter(path => path.startsWith(sourceRoot + '/') || path.startsWith(sourceRoot + '\\'))].filter(path => path.endsWith('.aug')))) {
         const parsed = read(path);
         files.set(path, parsed.file);
         diagnostics.push(...parsed.diagnostics);
@@ -70,7 +71,7 @@ export function loadProject(projectRoot, overrides = new Map(), cache) {
         }
     const libraries = standardLibraries();
     const stdlibRoot = libraries.root;
-    const libraryFiles = new Set([stdlibRoot, ...libraries.modules.values()].flatMap(sourceFiles));
+    const libraryFiles = new Set([join(stdlibRoot, 'export.aug'), ...sourceFiles(join(stdlibRoot, 'io'))]);
     for (const path of libraryFiles) {
         const parsed = read(path);
         parsed.file.builtin = true;
@@ -90,14 +91,14 @@ export function loadProject(projectRoot, overrides = new Map(), cache) {
             if (!isExport && item.kind === 'export') {
                 diagnostics.push(diagnostic(file.path, item.span.line, item.span.column, 'export declarations belong in export.aug', 'EXPORT'));
             }
-            if (file === main && ['class', 'interface', 'function', 'interceptor', 'test', 'composition'].includes(item.kind)) {
+            if (file === main && ['class', 'interface', 'function', 'interceptor', 'test', 'composition', 'resource'].includes(item.kind)) {
                 diagnostics.push(diagnostic(file.path, item.span.line, item.span.column, 'Define classes, interfaces, functions, and interceptors outside main.aug', 'MAIN'));
             }
             if (file !== main && ['bind', 'include', 'expr', 'assign', 'return', 'throw', 'if', 'while', 'for', 'destructure', 'match', 'scope', 'freeze', 'serve', 'lock',
                 'try', 'unsafe', 'borrow'].includes(item.kind)) {
                 diagnostics.push(diagnostic(file.path, item.span.line, item.span.column, 'Executable statements and bindings belong in main.aug', 'MAIN'));
             }
-            if (item.kind === 'class' || item.kind === 'interface' || item.kind === 'function' || item.kind === 'interceptor' || item.kind === 'composition') {
+            if (item.kind === 'class' || item.kind === 'interface' || item.kind === 'function' || item.kind === 'interceptor' || item.kind === 'composition' || item.kind === 'resource') {
                 if (item.name in builtinTypes || builtinFunctions.some(operation => operation.name === item.name) || item.name === 'next') {
                     diagnostics.push(diagnostic(file.path, item.span.line, item.span.column, `${item.name} is a reserved built-in name`, 'NAME'));
                     continue;
@@ -216,7 +217,7 @@ export function loadProject(projectRoot, overrides = new Map(), cache) {
             }
             return result;
         };
-        const privateModule = item.from.find(isPrivateName);
+        const privateModule = item.from.slice(isGitSource(item.from[0]) ? 1 : 0).find(isPrivateName);
         if (privateModule) {
             diagnostics.push(diagnostic(importer, item.span.line, item.span.column, `Cannot import from private module ${privateModule}`, 'PRIVATE'));
             return result;
@@ -234,7 +235,8 @@ export function loadProject(projectRoot, overrides = new Map(), cache) {
         }
         const owner = files.get(importer)?.package;
         const ownerScope = owner ? packages.scopes.get(owner) : undefined;
-        const dependency = ownerScope ? packages.scopes.get(ownerScope.dependencies[item.from[0]]) : packages.roots.get(item.from[0]);
+        const alias = isGitSource(item.from[0]) ? sourceAlias(item.from[0]) : item.from[0];
+        const dependency = ownerScope ? packages.scopes.get(ownerScope.dependencies[alias]) : packages.roots.get(alias);
         if (dependency) {
             let folder = dependency.sourceRoot;
             for (const child of item.from.slice(1)) {

package/src/runtime-abi.js

@@ -0,0 +1,23 @@
+import { createHash } from 'node:crypto';
+import { httpPolicyNames, httpPolicyNativeName } from "./http-policies.js";
+/** Compiler-private identifiers, checked against the compiled target headers. */
+export const runtimeOperations = ['PRINT', 'BINARY', 'UNARY', 'FIELD', 'SET_FIELD', 'LIST', 'TUPLE', 'SET', 'MAP', 'MAP_SET', 'LIST_LENGTH', 'LIST_GET', 'LIST_AT', 'LIST_APPEND', 'TUPLE_LENGTH', 'TUPLE_GET', 'SET_LENGTH', 'SET_ADD', 'SET_CONTAINS', 'MAP_LENGTH', 'MAP_GET', 'MAP_TAKE', 'MAP_CONTAINS', 'STRING_LENGTH', 'STRING_BYTES', 'STRING_SPLIT', 'STRING_STARTS_WITH', 'STRING_IS_TOKEN', 'BYTES_LENGTH', 'BYTES_TEXT', 'BYTES_BASE64URL', 'BASE64URL_DECODE', 'C_INT', 'READ_FILE', 'WRITE_FILE', 'ARGUMENTS', 'FREEZE', 'ITER', 'MAP_ITER', 'IS_TYPE', 'SHARED', 'SHARED_LOCK', 'JSON_WRAP', 'JSON_PARSE', 'JSON_STRINGIFY', 'JSON_GET', 'JSON_REQUIRE', 'JSON_STRING', 'JSON_INTEGER', 'JSON_BOOLEAN', 'JSON_ITEMS', 'TIME_NOW', 'EXIT', 'TEST_CASE'];
+export const httpOperations = ['HTTP_HEADERS', 'HTTP_HEADERS_WITH', 'HTTP_HEADERS_GET', 'HTTP_HEADERS_ALL', 'HTTP_RESPONSE', 'HTTP_RESPONSE_STATUS', 'HTTP_FINISH', 'HTTP_EVENT', 'HTTP_YIELD', 'HTTP_CLIENT_REQUEST', 'HTTP_ACTION'];
+/** Every private operation declares either a fixed or a collection arity. */
+export const runtimeArities = {
+    PRINT: 1, BINARY: 2, UNARY: 1, FIELD: 1, SET_FIELD: 2, LIST: 'variadic', TUPLE: 'variadic', SET: 'variadic', MAP: 0, MAP_SET: 3,
+    LIST_LENGTH: 1, LIST_GET: 2, LIST_AT: 2, LIST_APPEND: 2, TUPLE_LENGTH: 1, TUPLE_GET: 2, SET_LENGTH: 1, SET_ADD: 2, SET_CONTAINS: 2,
+    MAP_LENGTH: 1, MAP_GET: 2, MAP_TAKE: 2, MAP_CONTAINS: 2, STRING_LENGTH: 1, STRING_BYTES: 1, STRING_SPLIT: 2, STRING_STARTS_WITH: 2, STRING_IS_TOKEN: 3,
+    BYTES_LENGTH: 1, BYTES_TEXT: 1, BYTES_BASE64URL: 1, BASE64URL_DECODE: 1, C_INT: 1, READ_FILE: 1, WRITE_FILE: 2, ARGUMENTS: 0, FREEZE: 1, ITER: 1, MAP_ITER: 1, IS_TYPE: 1,
+    SHARED: 1, SHARED_LOCK: 1, JSON_WRAP: 1, JSON_PARSE: 1, JSON_STRINGIFY: 1, JSON_GET: 2, JSON_REQUIRE: 2, JSON_STRING: 1, JSON_INTEGER: 1, JSON_BOOLEAN: 1, JSON_ITEMS: 1,
+    TIME_NOW: 0, EXIT: 1, TEST_CASE: 0, HTTP_HEADERS: 0, HTTP_HEADERS_WITH: 3, HTTP_HEADERS_GET: 2, HTTP_HEADERS_ALL: 2, HTTP_RESPONSE: 3, HTTP_RESPONSE_STATUS: 2,
+    HTTP_FINISH: 1, HTTP_EVENT: 4, HTTP_YIELD: 1, HTTP_CLIENT_REQUEST: 5, HTTP_ACTION: 'variadic',
+};
+export const schemaKinds = ['INT', 'C_INT', 'FLOAT', 'BOOL', 'STRING', 'LIST', 'MAP', 'SET', 'TUPLE', 'RECORD', 'JSON'];
+export const runtimeIdentifiers = Object.fromEntries([
+    ...runtimeOperations.map((name, index) => ['AUG_IR_' + name, index + 1]),
+    ...httpOperations.map((name, index) => ['AUG_IR_' + name, index + 1]),
+    ...schemaKinds.map((name, index) => ['AUG_SCHEMA_' + name, index]),
+    ...httpPolicyNames.map((name, index) => [httpPolicyNativeName(name), index + 1]),
+]);
+export const runtimeIdentifierSha256 = createHash('sha256').update(JSON.stringify(runtimeIdentifiers)).digest('hex');

package/src/runtime-adapters.js

@@ -0,0 +1,18 @@
+export const runtimeAdapters = [
+    { name: '_aug_crypto_random', parameters: ['int'], returns: 'Bytes', component: 'crypto' },
+    { name: '_aug_crypto_sha256', parameters: ['Bytes'], returns: 'Bytes', component: 'crypto' },
+    { name: '_aug_crypto_generate_rsa', parameters: [], returns: 'RsaPrivateKey', component: 'crypto' },
+    { name: '_aug_crypto_public_rsa', parameters: ['RsaPrivateKey'], returns: 'RsaPublicKey', component: 'crypto' },
+    { name: '_aug_crypto_sign_rsa', parameters: ['RsaPrivateKey', 'Bytes'], returns: 'Bytes', component: 'crypto' },
+    { name: '_aug_crypto_verify_rsa', parameters: ['RsaPublicKey', 'Bytes', 'Bytes'], returns: 'bool', component: 'crypto' },
+    { name: '_aug_crypto_decode_base64url', parameters: ['string'], returns: 'Bytes', component: 'crypto' },
+    { name: '_aug_crypto_equal', parameters: ['Bytes', 'Bytes'], returns: 'bool', component: 'crypto' },
+    { name: '_aug_crypto_export_rsa', parameters: ['RsaPublicKey'], returns: 'Tuple<Bytes,Bytes>', component: 'crypto' },
+    { name: '_aug_crypto_import_rsa', parameters: ['Bytes', 'Bytes'], returns: 'RsaPublicKey', component: 'crypto' },
+    { name: '_aug_crypto_password_hash', parameters: ['Bytes', 'Bytes', 'int'], returns: 'Bytes', component: 'crypto' },
+    { name: '_aug_http_log', parameters: ['string', 'string', 'int', 'int'], returns: 'void', component: 'http' },
+    { name: '_aug_http_request', parameters: ['string', 'string', 'optional Headers', 'optional Bytes'], returns: 'HttpResponse<Bytes>', component: 'http' },
+    { name: '_aug_http_url_encode', parameters: ['string'], returns: 'string', component: 'http' },
+    { name: '_aug_http_cookie', parameters: ['string', 'string', 'string', 'int', 'bool'], returns: 'Headers', component: 'http' }
+];
+export function adapterSymbol(adapter) { return 'aug_ir_private' + adapter.name; }

package/src/schemas.js

@@ -21,11 +21,10 @@ export function jsonDataType(project, type, seen = new Set()) {
     const params = new Map(node.typeParams.map((name, i) => [name, type.args[i]]));
     return node.fields.every(field => jsonDataType(project, schemaType(project, field.type, type.def.file, params), seen));
 }
-/** One shared native schema per concrete type, used by HTTP and explicit JSON decoding. */
-export class NativeSchemas {
+/** Backend-neutral, resolved schema graph shared by HTTP and JSON decoding. */
+export class DataSchemas {
     names = new Map();
-    output = [];
-    forwards = [];
+    nodes = [];
     project;
     constructorName;
     constructor(project, constructorName) {
@@ -39,24 +38,32 @@ export class NativeSchemas {
             return previous;
         const name = 'aug_schema_' + this.names.size;
         this.names.set(key, name);
-        this.forwards.push(`static const AugSchema ${name};`);
-        let kind = 'AUG_SCHEMA_' + type.name.toUpperCase(), fields = [], labels = [], maker = 'NULL';
+        const schema = { name, kind: type.name.toUpperCase(), nullable: type.nullable,
+            optional: !!type.optional, fields: [], labels: [] };
+        this.nodes.push(schema);
         if (type.def?.node.kind === 'class' && type.def.node.record) {
-            kind = 'AUG_SCHEMA_RECORD';
+            schema.kind = 'RECORD';
             const node = type.def.node, params = new Map(node.typeParams.map((param, i) => [param, type.args[i]]));
-            fields = node.fields.map(field => '&' + this.request(schemaType(this.project, field.type, type.def.file, params)));
-            labels = node.fields.map(field => JSON.stringify(field.name));
-            maker = this.constructorName(type.def);
+            schema.fields = node.fields.map(field => this.request(schemaType(this.project, field.type, type.def.file, params)));
+            schema.labels = node.fields.map(field => field.name);
+            schema.maker = this.constructorName(type.def);
         }
         else
-            fields = type.args.map(arg => '&' + this.request(arg));
-        if (fields.length)
-            this.output.push(`static const AugSchema *const ${name}_fields[] = {${fields.join(', ')}};`);
-        if (labels.length)
-            this.output.push(`static const char *const ${name}_names[] = {${labels.join(', ')}};`);
-        this.output.push(`static const AugSchema ${name} = {${kind}, ${type.nullable ? 'true' : 'false'}, ${type.optional ? 'true' : 'false'}, ${fields.length}, ${fields.length ? name + '_fields' : 'NULL'}, ${labels.length ? name + '_names' : 'NULL'}, ${maker}};`);
+            schema.fields = type.args.map(arg => this.request(arg));
         return name;
     }
     identity(type) { return [type.id, type.nullable, !!type.optional, type.args.map(arg => this.identity(arg))]; }
-    declarations() { return [...this.forwards, ...this.output].join('\n'); }
+}
+/** C representation of the same checked concrete schema graph. */
+export class NativeSchemas extends DataSchemas {
+    declarations() {
+        return [...this.nodes.map(schema => `static const AugSchema ${schema.name};`), ...this.nodes.flatMap(schema => {
+                const { name, fields, labels } = schema;
+                return [
+                    ...(fields.length ? [`static const AugSchema *const ${name}_fields[] = {${fields.map(field => '&' + field).join(', ')}};`] : []),
+                    ...(labels.length ? [`static const char *const ${name}_names[] = {${labels.map(label => JSON.stringify(label)).join(', ')}};`] : []),
+                    `static const AugSchema ${name} = {AUG_SCHEMA_${schema.kind}, ${schema.nullable ? 'true' : 'false'}, ${schema.optional ? 'true' : 'false'}, ${fields.length}, ${fields.length ? name + '_fields' : 'NULL'}, ${labels.length ? name + '_names' : 'NULL'}, ${schema.maker ?? 'NULL'}, NULL};`
+                ];
+            })].join('\n');
+    }
 }

package/src/semantic.js

@@ -11,6 +11,8 @@ import { javadocBefore } from "./javadoc.js";
 import { checkUnitTests, discoverTests, mergeTestAnalysis, uniqueDiagnostics } from "./testing.js";
 import { formatFile } from "./formatter.js";
 import { interceptorBehavior } from "./interceptors.js";
+import { callableResult, callableErrors } from "./contracts.js";
+import { nativeFact, nativeDependencies } from "./native-facts.js";
 const genericFacts = (header) => header.typeParams.map(name => ({ name,
     variance: header.typeVariance?.[name] ?? 'invariant', constraints: (header.typeConstraints?.[name] ?? []).map(typeName) }));
 export function contractFacts(checked) {
@@ -18,18 +20,21 @@ export function contractFacts(checked) {
     const callable = (method, constructor) => {
         const contract = checked.effectContracts.get(method);
         const layers = checked.interceptorPlans.get(constructor ?? method) ?? [];
+        const native = nativeFact(checked, method);
         return { name: method.name, location: method.span, genericParameters: genericFacts(method),
+            native: native?.kind === 'function' ? native : undefined, nativeDependencies: nativeDependencies(checked, method), nativeCoverage: 'resolved-standalone-calls',
             inputs: method.params.map(param => ({ label: param.label ?? param.name, name: param.name,
                 type: typeName(param.type), ownership: param.ownership, injected: param.injected, source: param.source })),
             http: method.endpoint ? { method: method.endpoint.method, path: method.endpoint.path, status: method.endpoint.status,
                 streaming: !!method.endpoint.streams, errors: method.endpoint.errors.map(error => ({ type: typeName(error.type), status: error.status })) } : undefined,
             policies: (checked.httpPolicies.get(method) ?? []).map((policy, index) => ({ name: policy.name, order: index + 1, options: policy.options,
                 dependencies: policy.dependencies.map(index => method.params[index]?.label ?? method.params[index]?.name ?? '') })),
-            result: `${method.returnOwnership === 'own' ? 'own ' : ''}${typeName(method.returns)}`,
+            result: `${method.returnOwnership === 'own' ? 'own ' : ''}${tyName(callableResult(checked, method))}`,
             changes: [...(contract?.changes ?? method.changes ?? [])],
-            capabilities: [...(contract?.uses.values() ?? [])].map(effect => `${effect.source}.${effect.operation}`).concat(method.externC ? [`C.${method.name}`] : []),
+            capabilities: [...(contract?.uses.values() ?? [])].map(effect => `${effect.source}.${effect.operation}`).concat(method.externC && !native ? [`C.${method.name}`] : []),
             inferredEffects: !!contract?.inferred,
-            errors: [...new Set([...method.throws.map(typeName), ...layers.flatMap(layer => layer.errors.map(tyName))])],
+            errors: constructor ? [...new Set([...(checked.constructorContracts.get(constructor)?.errors.map(tyName) ?? constructor.validationErrors?.map(typeName) ?? []),
+                    ...layers.flatMap(layer => layer.errors.map(tyName))])].sort() : callableErrors(checked, method),
             interceptors: layers.map((layer, order) => {
                 const effects = checked.effectContracts.get(layer.around);
                 return { name: layer.definition.name, order: order + 1, location: layer.definition.node.span,
@@ -66,8 +71,10 @@ export function contractFacts(checked) {
                     visit(child);
         };
         visit(node);
+        const native = node.kind === 'resource' ? nativeFact(checked, node) : undefined;
         return { id: def.id, name: def.name, kind: node.kind === 'class' && node.record ? 'record' :
                 node.kind === 'interface' && node.capability ? 'capability' : node.kind,
+            native: native?.kind === 'resource' ? native : undefined,
             location: node.span, public: !node.name.startsWith('_'), typeParameters: node.typeParams, genericParameters: genericFacts(node),
             documentation: javadocBefore(file.source, 'annotations' in node ? node.annotations?.[0]?.span.start ?? node.span.start : node.span.start)?.markdown,
             interfaces: node.kind === 'class' ? node.implements.map(typeName) : node.kind === 'interface' ? node.extends.map(typeName) : [],
@@ -77,7 +84,7 @@ export function contractFacts(checked) {
                         typeConstraints: node.typeConstraints, typeVariance: node.typeVariance, params: node.fields,
                         returns: syntheticType(node.name, node.span), returnOwnership: 'managed',
                         throws: node.validationErrors ?? [], changes: [], uses: [], body: node.constructorBody, externC: false, span: node.span }, node)] : []),
-                ...methods.filter(method => !method.name.startsWith('_')).map(method => callable(method))], calls,
+                ...methods.filter(method => node.kind === 'function' || !method.name.startsWith('_')).map(method => callable(method))], calls,
             tests: file.items.flatMap(item => item.kind === 'test' && item.type.name === def.name ? item.groups.flatMap(group => group.cases.map(test => ({ group: group.name, name: test.name, location: test.span }))) : []) };
     });
 }
@@ -145,7 +152,7 @@ export function describe(checked, fileName, options = {}) {
             const module = { file: source.path, dependencies: [...new Set(source.items.flatMap(item => item.kind === 'import' ?
                         (checked.project.imports.get(item) ?? []).map(def => def.file) : []))].sort(),
                 public: publicFacts.map(fact => ({ name: fact.name, shape: createHash('sha256').update(JSON.stringify({ kind: fact.kind,
-                        generics: fact.genericParameters, fields: fact.fields.filter(field => !field.storage.startsWith('_')),
+                        native: fact.native, generics: fact.genericParameters, fields: fact.fields.filter(field => !field.storage.startsWith('_')),
                         interfaces: fact.interfaces, callables: fact.callables.map(({ location, interceptors, inputs, ...contract }) => ({ ...contract,
                             inputs: inputs.map(({ name, ...input }) => input),
                             interceptors: interceptors.map(({ location, ...layer }) => layer) })) })).digest('hex') })),
@@ -186,6 +193,48 @@ export class SemanticDocument {
     complete(offset) { return completions(this.checked, this.path, offset); }
     tokens() { return semanticTokens(this.checked, this.path); }
     fixes() { return suggestedFixes(this.checked, this.path); }
+    /** Non-editable declaration hints. Formatting never adds inferred source clauses. */
+    inlayHints(start = 0, end = this.source.length) {
+        const hints = [];
+        for (const [method, contract] of this.checked.callableContracts) {
+            if (method.span.file !== this.path || !method.body || method.headerEnd === undefined)
+                continue;
+            let offset = method.headerEnd;
+            while (offset > method.span.start && /\s/.test(this.source[offset - 1]))
+                offset--;
+            if (offset < start || offset > end)
+                continue;
+            const clauses = [];
+            if (contract.inferredResult && contract.result.kind !== 'error' && contract.result.name !== 'void')
+                clauses.push(contract.result.name === '<target result>' ? 'returns the target result' : `returns ${tyName(contract.result)}`);
+            const effects = this.checked.effectContracts.get(method);
+            if (effects?.inferredChanges && effects.changes.length)
+                clauses.push(`changes ${effects.changes.join(' and ')}`);
+            const uses = [...(effects?.uses.values() ?? [])].map(effect => `${effect.source}.${effect.operation}`).sort();
+            if (effects?.inferred && uses.length)
+                clauses.push(`uses ${[...new Set(uses)].join(' and ')}`);
+            const errors = callableErrors(this.checked, method);
+            if (contract.inferredErrors && errors.length)
+                clauses.push(`unless ${errors.join(' and ')}`);
+            const complete = clauses.join(' ');
+            const compact = complete.length > 120 ? clauses.map(clause => clause.startsWith('uses ') && clause.length > 50 ? `uses ${new Set(uses).size} operations` :
+                clause.startsWith('unless ') && clause.length > 50 ? `unless ${errors.length} errors` : clause).join(' ') : complete;
+            if (clauses.length)
+                hints.push({ offset, label: compact,
+                    tooltip: `\`\`\`augscript\n${complete}\n\`\`\`\n\n` + 'Inferred from the body, implemented interface, and interceptor layers. These hints are not source text. The compiler still checks ownership, interface limits, and escaping errors. See the adjacent .aug.md spec for the full explanation.' });
+        }
+        for (const [record, contract] of this.checked.constructorContracts) {
+            if (record.span.file !== this.path || !contract.inferredErrors || !contract.errors.length || record.headerEnd === undefined)
+                continue;
+            let offset = record.headerEnd;
+            while (offset > record.span.start && /\s/.test(this.source[offset - 1]))
+                offset--;
+            if (offset >= start && offset <= end)
+                hints.push({ offset, label: 'unless ' + contract.errors.map(tyName).sort().join(' and '),
+                    tooltip: 'Checked errors inferred from record validation. Callers must catch or propagate them. These hints are not saved source.' });
+        }
+        return hints.sort((left, right) => left.offset - right.offset);
+    }
     format() { return formatFile(this.checked.project, this.checked.project.files.get(this.path)); }
     describe(options) { return describe(this.checked, this.path, options); }
     definition(offset) {

package/src/snippets.js

@@ -0,0 +1,60 @@
+/** Small starting points for ordinary August declarations and statements. */
+export const snippetCatalog = [
+    { prefix: 'record', description: 'Immutable data with named fields', body: 'record ${1:User}(${2:string name})' },
+    { prefix: 'interface', description: 'A public behavior contract', body: 'interface ${1:Greeter}:\n    ${2:greet}(${3:string name}) returns ${4:string}' },
+    { prefix: 'capability', description: 'An explicit I/O contract', body: 'capability ${1:Logger}:\n    ${2:log}(${3:string message}) uses ${1:Logger}.${2:log}' },
+    { prefix: 'implementation', description: 'A class implementing an interface', body: '${1:SimpleGreeter}(${2:resolve Logger logger}) implements ${3:Greeter}:\n    ${4:greet}(${5:string name}):\n        $0' },
+    { prefix: 'method', description: 'A function or method with an inferred result', body: '${1:calculate}(${2:int value}):\n    $0' },
+    { prefix: 'generic', description: 'A generic identity function', body: '${1:identity}<T>(T value):\n    return value' },
+    { prefix: 'initialize', description: 'Initialize constructor fields or validate a record', body: 'initialize:\n    $0' },
+    { prefix: 'import', description: 'Import a public declaration', body: 'import ${1:Name} from ${2:module}' },
+    { prefix: 'importurl', description: 'Import directly from a public Git repository', body: 'import ${1:Name} from "https://github.com/${2:owner}/${3:library}"' },
+    { prefix: 'export', description: 'Expose one declaration from a sibling file', body: 'export ${1:Name} from ${2:file}' },
+    { prefix: 'exportfolder', description: 'Expose a child module with its own export.aug', body: 'export folder ${1:module}' },
+    { prefix: 'implement', description: 'Select a dependency provider in main.aug', body: 'implement ${1:Contract} with ${2:Provider}' },
+    { prefix: 'resolve', description: 'Resolve a dependency explicitly', body: 'resolve ${1:Contract} to ${2:service}' },
+    { prefix: 'if', description: 'Conditional code', body: 'if ${1:condition}:\n    $0' },
+    { prefix: 'ifelse', description: 'Two alternatives', body: 'if ${1:condition}:\n    $2\nelse:\n    $0' },
+    { prefix: 'for', description: 'Visit collection values', body: 'for ${1:item} in ${2:items}:\n    $0' },
+    { prefix: 'while', description: 'Repeat while a condition holds', body: 'while ${1:condition}:\n    $0' },
+    { prefix: 'matchoptional', description: 'Handle a value or null', body: 'match ${1:value}:\n    when some ${2:item}:\n        $3\n    when null:\n        $0' },
+    { prefix: 'try', description: 'Recover from a checked failure', body: 'try:\n    $1\ncatch ${2:FileError} ${3:error}:\n    $0' },
+    { prefix: 'borrow', description: 'Grant bounded mutable access', body: 'borrow ${1:value}:\n    $0' },
+    { prefix: 'scope', description: 'Start and join a child computation', body: 'scope:\n    ${1:pending} = start ${2:load}(${3:})\n    wait for ${1:pending} as ${4:result}\n    $0' },
+    { prefix: 'waitall', description: 'Join two computations', body: 'wait for ${1:loadingUsers} and ${2:loadingOrders} as ${3:users} and ${4:orders}' },
+    { prefix: 'lock', description: 'Access shared mutable state inside a bounded lock', body: 'lock ${1:shared} as ${2:value}:\n    $0' },
+    { prefix: 'unsafe', description: 'Contain a native C call', body: 'unsafe:\n    $0' },
+    { prefix: 'resource', description: 'An opaque native package resource with checked cleanup', body: 'extern C resource ${1:Handle}' },
+    { prefix: 'serve', description: 'Start a native HTTP listener', body: 'serve ${1:endpoint} on port ${2:8787}' },
+    ...['GET', 'POST', 'PATCH', 'DELETE'].map(method => ({ prefix: 'endpoint' + method.toLowerCase(), description: `A typed ${method} endpoint`, body: `endpoint ${method} "\${1:/items}" as \${2:handler}(\${3:}):\n    $0` })),
+    { prefix: 'stream', description: 'An endpoint yielding server-sent events', body: 'endpoint GET "${1:/events}" as ${2:events}() streams ServerEvent<string>:\n    yield ServerEvent(data=${3:"hello"})' },
+    { prefix: 'component', description: 'An embeddable server-rendered HTML component', body: '${1:Heading}(string text) returns Html:\n    return <h1>{text}</h1>' },
+    { prefix: 'test', description: 'A same-file function test', body: 'test ${1:calculate}:\n    when ${2:inputs}:\n        it ${3:works}:\n            assert(condition=${4:true})' },
+    { prefix: 'testclass', description: 'Fresh setup for each class test', body: 'test ${1:Worker} ${2:worker}:\n    when ${3:ready}:\n        ${2:worker} = ${1:Worker}(${4:})\n        it ${5:works}:\n            assert(condition=${6:true})' },
+    { prefix: 'testendpoint', description: 'Exercise the real endpoint pipeline', body: 'test endpoint ${1:handler} client:\n    when requests:\n        it succeeds:\n            response = client.request(method="GET", path="${2:/items}")\n            assert(condition=response.status == 200)' },
+    { prefix: 'it', description: 'A named test case', body: 'it ${1:works}:\n    assert(condition=${2:true})' },
+    { prefix: 'fixture', description: 'A reusable same-file test fixture', body: 'fixture ${1:sample}():\n    return ${2:42}' },
+    { prefix: 'interceptor', description: 'Wrap a call and preserve its result', body: 'interceptor ${1:Audit}<T>():\n    around():\n        result = next()\n        $0\n        return result' },
+    { prefix: 'javadoc', description: 'Document intent and labeled inputs', body: '/**\n * ${1:Explain why this declaration exists.}\n * @param ${2:name} ${3:What the input means.}\n */' },
+];
+export function snippetBody(body, style, tabs = false) {
+    if (style === 'braces') {
+        const result = [];
+        let depth = 0;
+        for (const line of body.split('\n')) {
+            const level = Math.floor((/^ */.exec(line)?.[0].length ?? 0) / 4);
+            while (depth > level)
+                result.push('    '.repeat(--depth) + '}');
+            if (line.endsWith(':')) {
+                result.push(line.slice(0, -1) + ' {');
+                depth = level + 1;
+            }
+            else
+                result.push(line);
+        }
+        while (depth)
+            result.push('    '.repeat(--depth) + '}');
+        body = result.join('\n');
+    }
+    return tabs ? body.replace(/^(?: {4})+/gm, prefix => '\t'.repeat(prefix.length / 4)) : body;
+}

package/src/spec-hints.js

@@ -0,0 +1,56 @@
+import { existsSync, lstatSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, relative } from 'node:path';
+import { checkProject } from "./checker.js";
+import { loadProject } from "./project.js";
+import { checkUnitTests, discoverTests, mergeTestAnalysis } from "./testing.js";
+const marker = '// aug-spec: ';
+/** One compiler-managed pointer. It gives readers an action and a precise neighboring filename. */
+export function specHint(file) {
+    const newline = file.source.includes('\r\n') ? '\r\n' : '\n';
+    const pointer = marker + JSON.stringify(basename(file.path) + '.md') + ' explains this file. Read it before changes; refresh with aug spec.' + newline;
+    const old = file.source.startsWith(marker) ? (file.source.includes('\n') ? file.source.indexOf('\n') + 1 : file.source.length) : 0;
+    const body = old ? file.source.slice(old) : file.source;
+    return { file, text: pointer + body, lineOffset: old ? 0 : 1 };
+}
+/** Prepare hints before native emission so debugger/source-map lines use the updated sources. */
+export function updateSpecHints(checked) {
+    const hints = [...checked.project.files.values()].filter(file => !file.builtin && !file.package).map(specHint)
+        .filter(hint => hint.text !== hint.file.source);
+    if (!hints.length)
+        return checked;
+    if (checked.diagnostics.some(issue => issue.severity !== 'warning'))
+        throw new Error('Fix compiler errors before adding specification pointers');
+    for (const { file } of hints) {
+        const root = checked.project.root;
+        if (relative(root, file.path).startsWith('..'))
+            throw new Error('Specification pointer escapes the project');
+        let parent = dirname(file.path);
+        while (parent !== root && parent !== dirname(parent)) {
+            if (lstatSync(parent).isSymbolicLink())
+                throw new Error('Specification source directory is a symbolic link');
+            parent = dirname(parent);
+        }
+        if (lstatSync(file.path).isSymbolicLink())
+            throw new Error('Specification source is a symbolic link');
+        if (readFileSync(file.path, 'utf8') !== file.source)
+            throw new Error('Source changed during compilation; retry before generating specifications');
+    }
+    for (const { file, text } of hints) {
+        const temporary = file.path + '.aug-spec-tmp';
+        let created = false;
+        try {
+            writeFileSync(temporary, text, { flag: 'wx', mode: lstatSync(file.path).mode });
+            created = true;
+            renameSync(temporary, file.path);
+        }
+        finally {
+            if (created && existsSync(temporary))
+                rmSync(temporary);
+        }
+    }
+    const project = loadProject(checked.project.root), fresh = checkProject(project), discovery = discoverTests(project);
+    const tests = checkUnitTests(project, discovery.tests);
+    fresh.diagnostics.push(...discovery.diagnostics, ...tests.flatMap(test => test.checked.diagnostics));
+    mergeTestAnalysis(fresh, tests);
+    return fresh;
+}