@greenpandastudios/aug-cli 0.20.1 → 0.21.0

package/src/project.js

@@ -91,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;

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

@@ -12,6 +12,7 @@ import { checkUnitTests, discoverTests, mergeTestAnalysis, uniqueDiagnostics } f
 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) {
@@ -19,7 +20,9 @@ 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,
@@ -28,7 +31,7 @@ export function contractFacts(checked) {
                 dependencies: policy.dependencies.map(index => method.params[index]?.label ?? method.params[index]?.name ?? '') })),
             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: 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),
@@ -68,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) : [],
@@ -79,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 }))) : []) };
     });
 }
@@ -147,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') })),

package/src/snippets.js

@@ -24,6 +24,7 @@ export const snippetCatalog = [
     { 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"})' },

package/src/spec.js

@@ -11,6 +11,7 @@ import { compilerVersion } from "./package-manager.js";
 import { tyName } from "./types.js";
 import { action, attempt, branch, choice, coordinate, flow, loop, paragraph, renderSpecTree, scope, section, sequence, step } from "./spec-tree.js";
 import { specHint } from "./spec-hints.js";
+import { nativeFact, nativeDescription } from "./native-facts.js";
 const generated = '<!-- Generated by aug spec. Edit the August source, then regenerate. -->';
 const copied = '// Generated by aug spec. This is a copy of the installed dependency source.\n';
 const code = (value) => { const text = value.replaceAll('\n', '\\n'); const fence = '`'.repeat(1 + Math.max(0, ...(text.match(/`+/g) ?? []).map(part => part.length))); return fence + (text.startsWith('`') ? ' ' : '') + text + (text.endsWith('`') ? ' ' : '') + fence; };
@@ -44,12 +45,19 @@ export function generateSpecs(checked, options = {}) {
     }
     const queue = [...owned].sort((a, b) => compare(a.path, b.path));
     const seen = new Set(), outputs = hints.map(hint => ({ path: hint.file.path, text: hint.text, source: hint.file.path, kind: 'source-hint' }));
+    const contracts = new Map();
+    for (const [provider, path] of checked.native.providerDescriptors) {
+        const at = provider.lastIndexOf('@'), name = provider.slice(0, at), version = provider.slice(at + 1);
+        const destination = join(project.root, '.aug-spec', 'packages', name, version, 'native.abi.json');
+        contracts.set(provider, destination);
+        outputs.push({ path: destination, text: readFileSync(path, 'utf8'), source: path, kind: 'native-descriptor' });
+    }
     for (let index = 0; index < queue.length; index++) {
         const file = queue[index];
         if (seen.has(file.path))
             continue;
         seen.add(file.path);
-        const writer = new SpecWriter(checked, file, docs, sources, own, offsets, path => {
+        const writer = new SpecWriter(checked, file, docs, sources, own, offsets, contracts, path => {
             const dependency = project.files.get(path);
             if (dependency && !seen.has(path))
                 queue.push(dependency);
@@ -67,20 +75,26 @@ class SpecWriter {
     sources;
     own;
     offsets;
+    contracts;
     enqueue;
     used = new Map();
     builtins = new Map();
     properties = new Map();
     locals = new Map();
-    constructor(checked, file, docs, sources, own, offsets, enqueue) {
+    constructor(checked, file, docs, sources, own, offsets, contracts, enqueue) {
         this.checked = checked;
         this.file = file;
         this.docs = docs;
         this.sources = sources;
         this.own = own;
         this.offsets = offsets;
+        this.contracts = contracts;
         this.enqueue = enqueue;
     }
+    nativeDescription(native) {
+        const contract = this.contracts.get(native.provider);
+        return nativeDescription(native, `[${code(native.descriptor)}](${url(relative(dirname(this.docs.get(this.file.path)), contract))})`);
+    }
     definition(name) { return this.checked.project.scopes.get(this.file.path)?.get(name); }
     use(def, method, field) {
         if (!def || def.file === this.file.path)
@@ -804,8 +818,10 @@ class SpecWriter {
         children.push(...this.contract(method, documentation), ...this.layers(method));
         if (method.body)
             children.push(flow(this.statements(method.body)));
-        else if (method.externC)
-            children.push(paragraph('Native C implementation; only its declared contract is visible here.'));
+        else if (method.externC) {
+            const native = nativeFact(this.checked, method);
+            children.push(paragraph(native ? this.nativeDescription(native) : 'Native C implementation; only its declared contract is visible here.'));
+        }
         return this.heading(name, method.span, owner && owner.node.kind !== 'function' ? 3 : 2, children);
     }
     exportLine(item) {
@@ -822,6 +838,10 @@ class SpecWriter {
     }
     declaration(item) {
         switch (item.kind) {
+            case 'resource': {
+                const native = nativeFact(this.checked, item);
+                return this.heading(item.name, item.span, 2, [paragraph(native ? this.nativeDescription(native) : code(item.name) + ' is an opaque native resource with an unresolved package release contract.')], 'native resource');
+            }
             case 'function': return this.callable(item);
             case 'class': {
                 const def = this.definition(item.name);
@@ -932,7 +952,7 @@ class SpecWriter {
     }
     render() {
         const exports = this.file.items.filter(item => item.kind === 'export');
-        const declarations = this.file.items.filter(item => ['class', 'interface', 'interceptor', 'function', 'composition'].includes(item.kind));
+        const declarations = this.file.items.filter(item => ['class', 'interface', 'interceptor', 'function', 'composition', 'resource'].includes(item.kind));
         const providers = this.file.items.filter(item => item.kind === 'bind' || item.kind === 'include');
         const startup = this.file.items.filter(item => item.kind !== 'import' && item.kind !== 'export' && item.kind !== 'test' && item.kind !== 'bind' && item.kind !== 'include' && !declarations.includes(item));
         const children = [];
@@ -982,18 +1002,28 @@ export function updateSpecs(checked, check = false, options = {}) {
     const outputs = generateSpecs(checked, options), root = checked.project.root;
     const manifest = join(root, '.aug-spec', 'manifest.json');
     let previous = [];
+    const previousDescriptors = new Map();
+    const descriptorPath = (path) => /^\.aug-spec\/packages\/(?:@[^/]+\/)?[^/]+\/[^/]+\/native\.abi\.json$/.test(path) && !path.includes('\\') && !path.split('/').some(part => part === '.' || part === '..');
     if (options.manifest !== false && existsSync(manifest)) {
         const saved = JSON.parse(readFileSync(manifest, 'utf8'));
-        if (saved.format !== 1 || !Array.isArray(saved.files) || saved.files.some(path => typeof path !== 'string' || relative(root, resolve(root, path)).startsWith('..') || !path.endsWith('.aug') && !path.endsWith('.aug.md')))
+        if (saved.format !== 1 || !Array.isArray(saved.files) || saved.files.some(path => typeof path !== 'string' || relative(root, resolve(root, path)).startsWith('..') || !path.endsWith('.aug') && !path.endsWith('.aug.md') && !descriptorPath(path)))
             throw new Error('Invalid generated specification manifest');
         previous = saved.files.map(path => resolve(root, path));
+        for (const [path, digest] of Object.entries(saved.nativeDescriptors ?? {})) {
+            if (!descriptorPath(path) || !saved.files.includes(path) || typeof digest !== 'string' || !/^[0-9a-f]{64}$/.test(digest))
+                throw new Error('Invalid generated native descriptor manifest');
+            previousDescriptors.set(resolve(root, path), digest);
+        }
     }
     const artifacts = outputs.filter(output => output.kind !== 'source-hint');
     const names = new Set(artifacts.map(output => output.path));
     const removed = previous.filter(path => !names.has(path) && existsSync(path));
     const stale = outputs.filter(output => !existsSync(output.path) || readFileSync(output.path, 'utf8') !== output.text).map(output => relative(root, output.path));
     stale.push(...removed.map(path => relative(root, path)));
-    const manifestText = JSON.stringify({ format: 1, files: artifacts.map(output => relative(root, output.path).replaceAll('\\', '/')), digest: hash(artifacts.map(output => output.text).join('\0')) }, null, 2) + '\n';
+    const descriptors = artifacts.filter(output => output.kind === 'native-descriptor');
+    const manifestText = JSON.stringify({ format: 1, files: artifacts.map(output => relative(root, output.path).replaceAll('\\', '/')),
+        ...(descriptors.length ? { nativeDescriptors: Object.fromEntries(descriptors.map(output => [relative(root, output.path).replaceAll('\\', '/'), hash(output.text)])) } : {}),
+        digest: hash(artifacts.map(output => output.text).join('\0')) }, null, 2) + '\n';
     if (options.manifest !== false && (!existsSync(manifest) || readFileSync(manifest, 'utf8') !== manifestText))
         stale.push('.aug-spec/manifest.json');
     if (check)
@@ -1016,10 +1046,21 @@ export function updateSpecs(checked, check = false, options = {}) {
                 if (text !== checked.project.files.get(output.source)?.source)
                     throw new Error('Source changed during compilation; retry before generating specifications');
             }
+            else if (output.kind === 'native-descriptor') {
+                // An unchanged descriptor from an earlier preview may be adopted. A
+                // tracked copy must still match its recorded bytes before replacement.
+                const tracked = previousDescriptors.get(output.path);
+                if (tracked ? hash(text) !== tracked : text !== output.text)
+                    throw new Error(`Refusing to overwrite edited native descriptor ${output.path}`);
+            }
             else if (!text.startsWith(generated) && !text.startsWith(copied))
                 throw new Error(`Refusing to overwrite handwritten file ${output.path}`);
         }
     }
+    for (const path of removed)
+        if (previousDescriptors.has(path) &&
+            (lstatSync(path).isSymbolicLink() || hash(readFileSync(path, 'utf8')) !== previousDescriptors.get(path)))
+            throw new Error(`Refusing to remove edited native descriptor ${path}`);
     for (const output of outputs) {
         if (existsSync(output.path) && readFileSync(output.path, 'utf8') === output.text)
             continue;
@@ -1038,7 +1079,7 @@ export function updateSpecs(checked, check = false, options = {}) {
     }
     for (const path of removed) {
         const text = readFileSync(path, 'utf8');
-        if (text.startsWith(generated) || text.startsWith(copied))
+        if (previousDescriptors.has(path) || text.startsWith(generated) || text.startsWith(copied))
             rmSync(path);
     }
     if (options.manifest !== false) {