@greenpandastudios/aug-cli 0.19.0

package/src/freshness.js

@@ -0,0 +1,154 @@
+/** Conservative proof that successful returns preserve constructor freshness. */
+export function returnsFresh(body, fields, freshCall) {
+    let valid = true;
+    const fresh = (expr, locals) => expr.kind === 'name' ?
+        locals.get(expr.name) === true : freshCall(expr);
+    const escape = (expr, locals) => {
+        if (expr.kind === 'start') {
+            escape(expr.call, locals);
+        }
+        else if (expr.kind === 'wait')
+            expr.tasks.forEach(task => escape(task, locals));
+        else if (expr.kind === 'handle' && expr.call.kind === 'call')
+            expr.call.args.forEach(child => escape(child, locals));
+        else if (expr.kind === 'markup')
+            [...expr.attributes.map(attribute => attribute.value), ...expr.children].forEach(child => escape(child, locals));
+        else if (expr.kind === 'collection') {
+            if (expr.items.some(item => fresh(item, locals)))
+                for (const name of locals.keys())
+                    locals.set(name, false);
+            expr.items.forEach(item => escape(item, locals));
+        }
+        else if (expr.kind === 'call') {
+            const isRead = expr.callee.kind === 'name' && ['next', 'print'].includes(expr.callee.name);
+            if (!isRead && expr.args.some(arg => fresh(arg, locals)))
+                for (const name of locals.keys())
+                    locals.set(name, false);
+            expr.args.forEach(arg => escape(arg, locals));
+        }
+        else if (expr.kind === 'binary') {
+            escape(expr.left, locals);
+            escape(expr.right, locals);
+        }
+        else if (expr.kind === 'unary')
+            escape(expr.value, locals);
+        else if (expr.kind === 'member')
+            escape(expr.object, locals);
+    };
+    const walk = (statements, locals) => {
+        for (const stmt of statements) {
+            if (stmt.kind === 'return') {
+                if (stmt.value)
+                    escape(stmt.value, locals);
+                if (!stmt.value || !fresh(stmt.value, locals))
+                    valid = false;
+                return false;
+            }
+            if (stmt.kind === 'throw') {
+                escape(stmt.value, locals);
+                return false;
+            }
+            if (stmt.kind === 'expr') {
+                escape(stmt.expr, locals);
+                continue;
+            }
+            if (stmt.kind === 'freeze') {
+                locals.set(stmt.name, false);
+                continue;
+            }
+            if (stmt.kind === 'serve') {
+                escape(stmt.port, locals);
+                continue;
+            }
+            if (stmt.kind === 'destructure') {
+                escape(stmt.value, locals);
+                stmt.names.forEach(name => locals.set(name, false));
+                continue;
+            }
+            if (stmt.kind === 'for') {
+                escape(stmt.iterable, locals);
+                const inside = new Map(locals);
+                stmt.names.forEach(name => inside.set(name, false));
+                walk(stmt.body, inside);
+                for (const name of locals.keys())
+                    if (inside.get(name) !== true)
+                        locals.set(name, false);
+                continue;
+            }
+            if (stmt.kind === 'match') {
+                escape(stmt.value, locals);
+                const states = stmt.cases.map(() => new Map(locals));
+                const continues = stmt.cases.map((clause, index) => walk(clause.body, states[index]));
+                if (continues.every(value => !value))
+                    return false;
+                for (const name of locals.keys())
+                    locals.set(name, states.every((state, index) => !continues[index] || state.get(name) === true));
+                continue;
+            }
+            if (stmt.kind === 'assign') {
+                escape(stmt.value, locals);
+                const value = fresh(stmt.value, locals);
+                if (stmt.target.kind === 'name' && !fields.has(stmt.target.name))
+                    locals.set(stmt.target.name, value);
+                else if (value)
+                    for (const name of locals.keys())
+                        locals.set(name, false);
+                continue;
+            }
+            if (stmt.kind === 'if') {
+                escape(stmt.test, locals);
+                if (stmt.test.kind === 'literal' && typeof stmt.test.value === 'boolean') {
+                    if (!walk(stmt.test.value ? stmt.then : stmt.otherwise, locals))
+                        return false;
+                    continue;
+                }
+                const left = new Map(locals), right = new Map(locals);
+                const leftContinues = walk(stmt.then, left), rightContinues = walk(stmt.otherwise, right);
+                if (!leftContinues && !rightContinues)
+                    return false;
+                for (const name of locals.keys())
+                    locals.set(name, (!leftContinues || left.get(name) === true) && (!rightContinues || right.get(name) === true));
+                continue;
+            }
+            if (stmt.kind === 'try') {
+                if (stmt.always) {
+                    const cleanup = new Map(locals);
+                    walk(stmt.always, cleanup);
+                    for (const name of locals.keys())
+                        if (!cleanup.get(name))
+                            locals.set(name, false);
+                }
+                const states = [new Map(locals), ...stmt.catches.map(() => new Map(locals))];
+                const continues = [walk(stmt.body, states[0]), ...stmt.catches.map((clause, i) => walk(clause.body, states[i + 1]))];
+                if (continues.every(value => !value))
+                    return false;
+                for (const name of locals.keys())
+                    locals.set(name, states.every((state, index) => !continues[index] || state.get(name) === true));
+                continue;
+            }
+            if (stmt.kind === 'while') {
+                if (stmt.test.kind === 'literal' && stmt.test.value === false)
+                    continue;
+                escape(stmt.test, locals);
+                const inside = new Map(locals);
+                walk(stmt.body, inside);
+                for (const name of locals.keys())
+                    if (inside.get(name) !== true)
+                        locals.set(name, false);
+                if (stmt.test.kind === 'literal' && stmt.test.value === true)
+                    return false;
+                continue;
+            }
+            if (stmt.kind === 'yield') {
+                escape(stmt.value, locals);
+                continue;
+            }
+            if (!walk(stmt.body, locals))
+                return false;
+        }
+        return true;
+    };
+    if (walk(body, new Map()))
+        valid = false;
+    return valid;
+}

package/src/help.js

@@ -0,0 +1,212 @@
+import { builtinFunctions } from "./builtins.js";
+const keyword = (detail, documentation) => ({ detail, documentation, category: 'keyword' });
+const type = (detail, documentation) => ({ detail, documentation, category: 'type' });
+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.' },
+    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.' },
+    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.' },
+    Compress: { category: 'tag', detail: '[Compress]', documentation: 'Negotiate gzip from Accept-Encoding, respecting q=0. Buffered output and each bounded stream item are compressed with standard gzip members. Adds Content-Encoding and Vary; backpressure remains active.' },
+    HttpTestClient: type('test endpoint getUser client: ...', 'A suite-supplied HTTP pipeline client. request(method="GET", path="/users/1", headers=..., body=...) returns HttpResponse<Bytes>. It exercises routing, decoding, request DI, policies, and serialization without a listening socket. Streaming collection is bounded by web.response_limit. Each it case runs with fresh test bindings.'),
+    input: keyword('handle createUser(input from form)', 'Read named form controls into the endpoint’s record input when a browser submits the action. Labels, scalar conversion, optional fields, and server schema validation follow the endpoint contract.'),
+    path: keyword('int id from path', 'Bind a required path placeholder by name. A label after the source can select a different wire name: int userId from path "id".'),
+    query: keyword('optional string search from query', 'Bind one query parameter. Omitted optional input becomes null; repeated scalar parameters are rejected.'),
+    header: keyword('optional string authorization from header "authorization"', 'Bind a case-insensitive HTTP field. Repeated scalar headers are rejected. Headers.all preserves repeated fields explicitly.'),
+    body: keyword('User input from body', 'Decode a concrete JSON data type. Malformed JSON returns 400; valid JSON with a wrong schema returns 422; wrong media type returns 415; body limits return 413.'),
+    form: keyword('Login input from form', 'Decode named application/x-www-form-urlencoded fields into a record. Unknown or repeated scalar fields are rejected. Typed handle actions supply form data with input from form.'),
+    cookie: keyword('optional string session from cookie "session"', 'Bind one named cookie. Missing input is distinct from an empty string, and repeated cookies are rejected.'),
+    request: keyword('HttpRequest request from request', 'Receive the immutable raw request when a protocol requires its own binding and error responses.'),
+    pure: keyword('extern C value pure operation(...)', 'A trusted native value adapter promises no effects or mutation. The foreign call still belongs inside unsafe; its declared errors remain checked.'),
+    optional: keyword('optional T value', 'Allow a value of T or null. Omitted optional inputs and fields become null. Match null and some, or check != null, before reading the value. This is the only optional type spelling; Type? is rejected.'),
+    missing: keyword('null', 'The missing keyword is rejected. Use null. An omitted optional value and an explicit null have the same language value; there is no separate missing state.'),
+    freeze: keyword('freeze ownValue as immutableValue', 'Consume owned mutable data and share one deeply frozen object. Surviving aliases cannot mutate it. Literal data can be frozen directly.'),
+    as: keyword('lock shared as state: ...', 'Name a local value, lock view, or HTTP endpoint. wait for accepts as or to for result names.'),
+    endpoint: keyword('endpoint GET "/users/{id}" as getUser(int id from path) returns User', 'Declare a typed HTTP route. Inputs name their wire source; dependencies use resolve. Main explicitly selects which endpoints to serve.'),
+    serve: keyword('serve getUser and createUser on port 8080', 'Start the native HTTP server with explicitly imported endpoints. Each request receives a separate DI and task scope.'),
+    streams: keyword('endpoint GET "/events" as events() streams ServerEvent<Event>', 'Declare a bounded streaming HTTP response. Yield values in wire order; disconnect cancels the request scope.'),
+    yield: keyword('yield value', 'Send a value from a streaming endpoint. Backpressure suspends the producer until the transport can accept it.'),
+    handle: keyword('handle updateUser(id=userId, input from form)', 'Describe a deferred call to a served endpoint. Inputs are checked against wire parameters; DI is resolved when the HTTP request runs. onSubmit and onClick accept HttpAction values, with automatic request transport.'),
+    start: keyword('task = start loadUsers()', 'Start a child task in a scope. Receiver and arguments evaluate immediately. Scheduled errors are checked at waits and implicit scope joins; an unhandled child error cancels siblings. A captured object cannot be mutated or moved by the parent while the child uses it. When start runs inside a loop, waiting for one result does not release captures from other iterations; the enclosing scope joins them all.'),
+    wait: keyword('wait for usersTask and ordersTask as users and orders', 'Wait for scoped tasks without changing result order. A List<Task<T>> produces List<T> and joins every child in the list. Waiting for one dynamically selected task leaves possible siblings captured until their scope joins them. A wait may encounter an unhandled sibling failure. Grouped waits observe all selected children before rethrowing the first failure. Waiting for I/O suspends a task.'),
+    always: keyword('try: ... always: ...', 'Run cleanup on success, checked errors, returns and cancellation. Cancellation bypasses ordinary catch blocks; cleanup runs before the scope ends.'),
+    lock: keyword('lock sharedValue as state: ...', 'Grant exclusive mutation of Shared<T> for a short block. Waiting, starting tasks, nested locks and I/O are forbidden inside. Unlocking is guaranteed on return or error.'),
+    Data: type('Data', 'A constraint for deeply immutable data: primitives, immutable records and frozen data collections. Behavioral objects cannot satisfy it.'),
+    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.'),
+    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.'),
+    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.'),
+    some: keyword('when some value: ...', 'Match the present case of a nullable value and introduce a read-only non-null name within the case body. Pair it with when null to cover absence explicitly.'),
+    shared: keyword('implement Logger with Adapter shared', 'Cache one stateless binding for the process. Sharing stateful instances requires an explicit shared mutable choice. A process binding cannot retain a scoped dependency.'),
+    fresh: keyword('implement Counter with CounterImpl fresh', 'Construct a new instance for each resolution. Stateful bindings use this lifetime by default, including objects that retain stateful dependencies.'),
+    scoped: keyword('implement Counter with CounterImpl scoped mutable', 'Cache a binding within a composition scope. Nested scope blocks have independent caches and restore the parent cache on exit. Stateful caching requires the explicit mutable choice.'),
+    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.'),
+    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.'),
+    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.'),
+    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`.'),
+    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.'),
+    everything: keyword('import everything from logging', 'Import every public declaration defined by a sibling file, or every public export listed in a folder’s export.aug. Private names and transitive imports are excluded. Name conflicts are compile errors. Explicit named imports make dependencies easier to understand.'),
+    test: keyword('test Calculator subject: ... or test add: ... or test endpoint getUser client: ...', 'Declare tests beside the class, function, or endpoint. Class suites initialize their subject; function suites omit a subject. Endpoint suites receive a native pipeline client. Parameterized it cases use for (inputs) in tuple rows. Tests are omitted from production executables; aug test selects groups/cases and --coverage records statement lines.'),
+    when: keyword('when GROUP_NAME { implement Dependency with Fake; ... }', 'Group related test cases and declare their test dependencies. Names may be identifiers or quoted descriptions. Put bindings first, then setup statements, then it cases. Each case re-runs setup with fresh bindings in a separate native process; production bindings and startup code do not run.'),
+    it: keyword('it TEST_NAME { assert(condition) }', 'Define a test case within a when group. Names may be identifiers or quoted descriptions. Group setup variables are visible, but other cases are not. Failed assertions and uncaught errors fail this case; the runner continues with the remaining cases. A case that executes no assertions fails.'),
+    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.'),
+    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.'),
+    bind: keyword('Use implement Interface with Implementation', 'This old binding spelling is rejected. Use implement Interface with Implementation. The editor migration fix or aug migrate --write upgrades old source without changing its binding contract.'),
+    implement: keyword('implement Interface with Implementation', 'Register an implementation in main or test setup. Stateless bindings are shared by default; stateful bindings are fresh. Choose shared mutable or scoped mutable explicitly when retaining mutable state. Headers supply all construction dependencies; binding order is independent and cycles are checked.'),
+    with: keyword('implement key with Class;', 'Separates a binding key from its implementing class. The class must satisfy an interface key.'),
+    to: keyword('destination to value', 'Alternative to = in assignments, typed declarations, labeled call arguments and interceptor mappings. Type publicLabel to _storage separates a public constructor input from private storage. resolve app to program retrieves a binding using its declared lifetime. Configure assignment in main.yaml for consistent formatting.'),
+    resolve: keyword('resolve Logger logger; resolve app to program', 'Declare a dependency in a class or callable header. Callers omit its argument and forward the matching header dependency. Only main and test setup retrieve bindings directly with resolve app to program. Assignment-form resolve is rejected. Scoped dependencies require a scope block.'),
+    class: keyword('No class keyword', 'Class declarations start with their name and must include `implements`: `Worker() implements IWorker { ... }`. Members starting with `_` are private to the class; other members are public. A private header field still accepts its labeled constructor argument. Remove the old `class` prefix.'),
+    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.'),
+    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`.'),
+    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`.'),
+    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.'),
+    else: keyword('else { ... }', 'Run this block when the preceding `if` condition is false.'),
+    while: keyword('while condition { ... }', 'Repeat a block while its condition remains `bool`.'),
+    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.'),
+    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.'),
+    null: keyword('null', 'The absent value of optional Type. Omitted optional inputs also become null. Narrow local values with if value != null, an early return guard, or match null/some before calling members. Fields remain conservative because another alias may change their value.'),
+    int: type('int', 'Signed 64-bit integer, from -9223372036854775808 to 9223372036854775807. Literals retain their exact value. Addition, subtraction, multiplication and MIN/-1 division wrap modulo 2^64. Dynamic division requires ArithmeticError handling. Mixed float arithmetic may lose integer precision.'),
+    float: type('float', 'Floating point number type. Arithmetic supports `+`, `-`, `*`, and `/`.'),
+    bool: type('bool', 'Boolean type used by conditions and logical operators.'),
+    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`.'),
+    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.'),
+    Map: type('Map<K,V>', 'Hash map: `{1: "apples", 2: "pears"}` infers Map<int, string>. A typed declaration supplies empty types: `Map<int, string> fruit = {}`. Duplicate keys keep the last value. `set(key=..., value=...)` requires mutable access; `get(key=...)` returns optional V; `contains(key=...)` and `length()` read. Primitive keys and tuples compare by value; other objects use identity.'),
+    assert: fn('assert(condition) returns void', 'Assert a bool inside a test or its group setup. `assert(condition=...)` also works. On failure, report the condition, file, and line; mark the case failed and raise an error. Catching that error cannot make the case pass. A case must execute at least one assertion.'),
+    print: fn('print(value=...) returns void', 'Write a value followed by a newline to standard output. The `value` label is required.'),
+    arguments: fn('arguments() returns List<string>', 'Read arguments after `--` when running a program: `aug run project -- first second`.'),
+    read_file: fn('read_file(path=string) returns string unless FileError', 'Read a UTF-8 text file. Catch `FileError` or declare it in the calling function.'),
+    write_file: fn('write_file(path=string, content=string) returns void unless FileError', 'Write UTF-8 text to a file. Catch `FileError` or declare it in the calling function.'),
+    '==': operator('left == right', 'Compare values for equality; the result is `bool`.'),
+    '!=': operator('left != right', 'Compare values for inequality; the result is `bool`.'),
+    '<': operator('left < right', 'Compare compatible numbers. Inside type arguments, `<` starts a generic argument list.'),
+    '<=': operator('left <= right', 'Compare compatible numbers; the result is `bool`.'),
+    '>': operator('left > right', 'Compare compatible numbers. Inside type arguments, `>` ends a generic argument list.'),
+    '>=': operator('left >= right', 'Compare compatible numbers; the result is `bool`.'),
+    '&&': operator('Use and', 'Symbolic boolean operators are rejected. Replace && with and; the right side is skipped when the left side is false.'),
+    '||': operator('Use or', 'Symbolic boolean operators are rejected. Replace || with or; the right side is skipped when the left side is true.'),
+    '!': operator('Use not', 'Symbolic boolean negation is rejected. The migration fix preserves grouping when replacing ! with not.'),
+    '+': operator('left + right', 'Add numbers or join strings.'),
+    '-': operator('left - right', 'Subtract numbers. Unary `-` negates a number.'),
+    '*': operator('left * right', 'Multiply numbers.'),
+    '/': operator('left / right', 'Divide numbers. Integer division truncates toward zero. A potentially zero divisor raises checked ArithmeticError; a literal nonzero divisor needs no error clause. MIN/-1 wraps to MIN.'),
+    '=': operator('name = value;', 'Assign a value. `to` is an equivalent assignment spelling: `name to value;` or `Type name to value;`. Use `own Type name to value;` for exclusive ownership.'),
+    '=>': operator('Use initialize', 'The arrow constructor spelling is rejected. Put initialize { ... } or its indented form inside the class or record. The editor migration fix moves the body and preserves behavior.'),
+    '?': operator('optional Type', 'Type? is rejected. Use optional Type for a value or null; omitted optional inputs and fields also become null. The migration fix upgrades the spelling.'),
+    '.': operator('receiver.member', 'Access a method or property. A member starting with `_` is private to its declaring type; other members are public. Mutable access still follows borrow rules.'),
+    ';': operator('statement;', 'Optional statement separator. Newlines, a closing block brace, or end of file also terminate statements. Use semicolons to separate several statements on one line. Expressions continue inside parentheses and collection literals, or after an unfinished operator.'),
+    '{': operator('{1, 2} or {1: "apples"}', 'Start a set literal, map literal, or statement block. Comma-separated values create a Set; key: value pairs create a Map. Empty {} needs a declared Set or Map type. Classes, interfaces, interceptors, tests, functions, and control flow use braces for blocks.'),
+    '}': operator('{ ... }', 'End a block, set literal, or map literal.'),
+    '(': operator('(1, 2)', 'Start a tuple, grouped expression, call argument list, function parameters, or class header. A comma creates a tuple; a single expression without a comma is grouping.'),
+    ')': operator('( ... )', 'End a tuple, grouped expression, argument list, parameter list, or class header.'),
+    ',': operator('first, second', 'Separate parameters, arguments, type arguments, or interfaces.'),
+    ':': operator('if condition: ... or {1: "apples"}', 'After a block header, introduce a body indented with tabs or spaces. Dedenting ends that body. Each block may independently use braces or indentation. In a map literal, separate a key from its value; collection and parenthesis continuation indentation has no block meaning.'),
+    '[': operator('[1, 2] or [Validator(y=x)]', 'Start a list literal, or an interceptor annotation immediately before a callable declaration. Lists infer one element type. Interceptor mappings connect processor labels to target labels; stacked annotations enter in written order.'),
+    ']': operator('[ ... ]', 'End a list literal or interceptor annotation.'),
+    '->': operator('->', 'This token is reserved for future syntax and is not currently valid AugScript.'),
+    '@param': { category: 'tag', detail: '@param name description', documentation: 'Document a parameter in the Javadoc comment immediately before a class, function, or method. The text appears in hover and signature help.' },
+    '@return': { category: 'tag', detail: '@return description', documentation: 'Document the returned value of a function or method.' },
+    '@returns': { category: 'tag', detail: '@returns description', documentation: 'Alias of `@return`.' },
+    '@throws': { category: 'tag', detail: '@throws ErrorType description', documentation: 'Document a declared error and when it is raised.' },
+    '@exception': { category: 'tag', detail: '@exception ErrorType description', documentation: 'Alias of `@throws`.' },
+    '@deprecated': { category: 'tag', detail: '@deprecated reason', documentation: 'Explain why this declaration should no longer be used.' },
+    '@see': { category: 'tag', detail: '@see OtherSymbol', documentation: 'Point readers to related declarations or documentation.' },
+    '@code': { category: 'tag', detail: '{@code expression}', documentation: 'Show an inline fragment as code in generated editor help.' },
+    '@link': { category: 'tag', detail: '{@link Type}', documentation: 'Show a related declaration name as code in generated editor help.' },
+    '@inheritDoc': { category: 'tag', detail: '{@inheritDoc}', documentation: 'Insert documentation from the implemented or extended interface method.' },
+};
+for (const operation of builtinFunctions)
+    if (!['int', 'c_int'].includes(operation.name))
+        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 = {
+    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.',
+    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.',
+    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.',
+    RECORD: 'Use deeply immutable data in record fields. Behavioral objects, mutable collections, resolve dependencies, and ownership belong in classes with explicit interfaces.',
+    MATCH: 'Cover true/false, null/some, or add else. Each pattern must be compatible with the value, and cases must remain reachable.',
+    PATTERN: 'Tuple patterns need exactly the same number of positions and introduce new names in the current scope.',
+    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.',
+    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.',
+    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.',
+    PARSE: 'Check braces, statement boundaries, declaration order, and Type name parameters. Semicolons are optional. Use unless for checked error contracts.',
+    CALL: 'Use a label for each ordinary argument, such as `Greeter(x=4)`. Omit parameters marked `resolve`.',
+    PROJECT: 'Create `main.aug` at the project root; it is the entry point.',
+    MAIN: 'Keep bindings and executable statements in `main.aug`; put declarations in other `.aug` files.',
+    EXPORT: 'Only `export` statements belong in `export.aug`. Export declarations name a sibling file.',
+    IMPORT: 'Import a sibling file directly or an exposed name from a folder’s `export.aug`.',
+    NAME: 'A name must be declared in this file or explicitly imported before use.',
+    TYPE: 'Check the types in the expression, parameters, return value, and generic arguments.',
+    INTERFACE: 'Every class declares at least one interface with `implements`. Implement its required methods with exact signatures, or use defaults.',
+    DI: 'Declare implement key with Class in main.aug before executable statements, or in a test when group before setup. Each key has one target class.',
+    OWN: 'An `own` value has one owner; move it into another `own` location or use ordinary managed storage.',
+    BORROW: 'Use `borrow value { ... }` around a mutation of a process managed value.',
+    THROWS: 'Catch the checked error with `try/catch` or declare it on the enclosing function.',
+    PRIVATE: 'A name starting with `_` is private to its file or declaring type. Private names, modules, and folders cannot be imported or exported.',
+    FFI: 'Declare C functions with `extern C name(...);` and call them inside `unsafe { ... }`.',
+};

package/src/html.js

@@ -0,0 +1,27 @@
+/** Server HTML accepts standard, inert elements; executable content uses endpoint actions. */
+export const htmlTags = new Set('html head title meta link body main header footer nav section article aside div span p h1 h2 h3 h4 h5 h6 a ul ol li dl dt dd table caption thead tbody tfoot tr th td form label input button select option optgroup textarea fieldset legend output progress meter img picture source video audio track figure figcaption details summary dialog pre code blockquote strong em b i u s small mark time br hr wbr area col embed param'.split(' '));
+export const htmlVoidTags = new Set('area br col embed hr img input link meta param source track wbr'.split(' '));
+export const htmlBooleanAttributes = new Set('disabled checked selected multiple required readonly autofocus hidden open controls loop muted autoplay novalidate formnovalidate reversed'.split(' '));
+export const htmlUrlAttributes = new Set(['href', 'src', 'action', 'formaction', 'poster']);
+const globals = new Set('id class className title lang dir role tabindex tabIndex style slot translate accesskey contenteditable draggable spellcheck'.split(' '));
+const attributes = {
+    html: 'xmlns', meta: 'name content charset http-equiv', link: 'rel href type media sizes crossorigin integrity',
+    a: 'href target rel download hreflang type', form: 'action method enctype autocomplete target name novalidate',
+    input: 'name type value placeholder required disabled checked readonly min max step minlength maxlength pattern autocomplete autofocus multiple accept form',
+    button: 'name type value disabled form formaction formmethod formnovalidate', label: 'for htmlFor form',
+    textarea: 'name placeholder rows cols required disabled readonly minlength maxlength autocomplete',
+    select: 'name required disabled multiple size form', option: 'value selected disabled label', optgroup: 'label disabled', fieldset: 'name disabled form',
+    img: 'src alt width height loading decoding crossorigin srcset sizes', source: 'src type srcset sizes media',
+    audio: 'src controls autoplay loop muted preload', video: 'src controls autoplay loop muted preload poster width height', track: 'src kind label srclang default',
+    th: 'colspan rowspan scope headers', td: 'colspan rowspan headers', ol: 'start reversed type', li: 'value',
+    progress: 'value max', meter: 'value min max low high optimum', details: 'open name', dialog: 'open', time: 'datetime', output: 'for name form',
+};
+export function htmlAttribute(tag, name) {
+    if (tag === 'form' && name === 'onSubmit' || tag === 'button' && name === 'onClick')
+        return 'HttpAction';
+    if (name.startsWith('data-') || name.startsWith('aria-'))
+        return 'string';
+    if (globals.has(name) || attributes[tag]?.split(' ').includes(name))
+        return htmlBooleanAttributes.has(name) ? 'bool' : 'string';
+    return undefined;
+}

package/src/http-policies.js

@@ -0,0 +1,90 @@
+export const httpPolicyNames = ['RequireLogin', 'RequirePermission', 'LogRequest', 'RateLimit', 'Timeout', 'Cors', 'Compress'];
+export function httpPolicyNativeName(name) {
+    return 'AUG_HTTP_POLICY_' + name.replace(/([a-z])([A-Z])/g, '$1_$2').toUpperCase();
+}
+export const httpPolicyOptions = {
+    RequireLogin: { authentication: 'dependency:Authentication.authenticate' },
+    RequirePermission: { authentication: 'dependency:Authentication.authenticate', authorization: 'dependency:Authorization.authorize', permission: 'string' },
+    LogRequest: { logger: 'dependency:RequestLogger.complete' },
+    RateLimit: { requests: 'int', seconds: 'int' }, Timeout: { milliseconds: 'int' },
+    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.',
+    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.',
+    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.',
+    origins: 'Literal list of exact HTTP(S) origins. "*" is allowed only without credentials. A disallowed supplied Origin returns 403.',
+    headers: 'Optional literal list of permitted CORS request header names. Preflight checks every requested header.',
+    credentials: 'Optional literal boolean enabling credentialed CORS. Default false; wildcard origins cannot enable it.',
+};
+/** Policy configuration is literal; service dependencies are explicit endpoint inputs. */
+export function checkHttpPolicy(annotation, fn, diagnostics, canonical) {
+    const name = annotation.name, options = {}, dependencies = [];
+    const report = (message) => diagnostics.push({ ...annotation.span, code: 'HTTP', message });
+    const specs = httpPolicyOptions;
+    const seen = new Set();
+    for (const entry of annotation.mappings) {
+        if (seen.has(entry.name)) {
+            report(`Duplicate ${name} option ${entry.name}`);
+            continue;
+        }
+        seen.add(entry.name);
+        const spec = specs[name][entry.name];
+        if (!spec) {
+            report(`${name} has no option ${entry.name}`);
+            continue;
+        }
+        if (spec.startsWith('dependency:')) {
+            const [type, operation] = spec.slice(11).split('.'), index = fn.params.findIndex(param => param.name === entry.source);
+            const param = fn.params[index];
+            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`);
+            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))
+                    report(`Declare uses ${param.name}.${operation} for ${name}`);
+            }
+            continue;
+        }
+        const value = entry.value, wanted = spec.replace(/^optional /, '');
+        const literal = (value) => value?.kind === 'literal';
+        if (wanted === 'strings' && value?.kind === 'collection' && value.collection === 'List' && value.items.every(item => literal(item) && typeof item.value === 'string'))
+            options[entry.name] = value.items.map(item => item.value);
+        else if (literal(value) && (wanted === 'string' && typeof value.value === 'string' || wanted === 'bool' && typeof value.value === 'boolean' || wanted === 'int' && typeof value.value === 'number' && value.numericType !== 'float' && Number.isSafeInteger(value.value)))
+            options[entry.name] = value.value;
+        else
+            report(`${name}.${entry.name} requires a literal ${wanted}`);
+    }
+    for (const [option, spec] of Object.entries(specs[name]))
+        if (!spec.startsWith('optional ') && !seen.has(option))
+            report(`${name} requires ${option}`);
+    if (annotation.typeArgs.length)
+        report(`${name} does not take type arguments`);
+    if (name === 'RateLimit' && (!Number.isInteger(options.requests) || Number(options.requests) < 1 || Number(options.requests) > 1000000 || !Number.isInteger(options.seconds) || Number(options.seconds) < 1 || Number(options.seconds) > 86400))
+        report('RateLimit requests must be 1..1000000 and seconds 1..86400');
+    if (name === 'Timeout' && (!Number.isInteger(options.milliseconds) || Number(options.milliseconds) < 1 || Number(options.milliseconds) > 3600000))
+        report('Timeout milliseconds must be 1..3600000');
+    if (name === 'RequirePermission' && (!options.permission || /[\x00-\x1f]/.test(String(options.permission))))
+        report('RequirePermission needs a nonempty permission without controls');
+    if (name === 'Cors') {
+        const origins = options.origins;
+        if (!origins?.length || origins.some(origin => { if (origin === '*')
+            return !!options.credentials; try {
+            const url = new URL(origin);
+            return !['https:', 'http:'].includes(url.protocol) || url.origin !== origin;
+        }
+        catch {
+            return true;
+        } }))
+            report('Cors origins are exact HTTP(S) origins; wildcard cannot use credentials');
+        if (options.headers?.some(header => !/^[!#$%&'*+.^_`|~0-9a-z-]+$/i.test(header)))
+            report('Cors headers contain HTTP field names');
+    }
+    return { name, annotation, options, dependencies };
+}

package/src/inference.js

@@ -0,0 +1,16 @@
+import { sameType, tyName } from "./types.js";
+/** One unification operation for callable and interceptor type arguments. */
+export function inferType(ref, actual, names, types, conflict, view = (_, actual) => actual) {
+    if (names.includes(ref.name) && !ref.args.length) {
+        const candidate = ref.nullable ? { ...actual, nullable: false, optional: false } : actual;
+        const previous = types.get(ref.name);
+        if (!previous)
+            types.set(ref.name, candidate);
+        else if (!sameType(previous, candidate))
+            conflict(`Conflicting inference for ${ref.name}: ${tyName(previous)} and ${tyName(candidate)}; supply compatible values or explicit type arguments`);
+        return;
+    }
+    const resolved = view(ref.name, actual);
+    if (resolved && ref.name === resolved.name && ref.args.length === resolved.args.length)
+        ref.args.forEach((arg, index) => inferType(arg, resolved.args[index], names, types, conflict, view));
+}