@ascent-lang/dev 0.1.0 → 0.3.0

package/src/interpreter.ts

@@ -1,6 +1,6 @@
 import type { BinaryOp } from './parser/ast.js';
 import type { TypedExpr, TypedBlock, TypedStatement, TypedProgram } from './parser/typed-ast.js';
-import type { AscentType } from './types/types.js';
+import { INT_TYPE, subtype, type AscentType } from './types/types.js';
 
 export type RuntimeValue = (
   | { type: 'Int'; value: bigint }
@@ -54,11 +54,11 @@ export class Environment {
   }
 }
 
-// Coerce a runtime value to match a target type when the target is Float
-// and the value is Int — the only implicit widening the language allows.
+// Coerce a runtime value to match a target type, per the witness `subtype`
+// produces — currently only Int <: Float, so only an Int value ever moves.
 // All other type conversions are explicit (methods like toFloat/toInt).
 const coerce = (v: RuntimeValue, targetType: AscentType): RuntimeValue => {
-  if (targetType.kind === 'Float' && v.type === 'Int') {
+  if (v.type === 'Int' && subtype(INT_TYPE, targetType) === 'intToFloat') {
     return { type: 'Float', value: Number(v.value) };
   }
   return v;
@@ -77,7 +77,8 @@ export const evaluateExpr = (expr: TypedExpr, env: Environment): RuntimeValue =>
       }
     }
     case 'slot': {
-      // N0001 / N0002 are caught at type-check time; this is an internal guard.
+      // Name-binding errors (N0001–N0003) are caught at type-check time; this
+      // is an internal guard.
       const value = env.get(expr.name);
       if (value === undefined) throw new Error(`internal: unbound slot '${expr.name}'`);
       return value;
@@ -119,12 +120,29 @@ export const evaluateExpr = (expr: TypedExpr, env: Environment): RuntimeValue =>
     }
     case 'unary': {
       const operand = evaluateExpr(expr.operand, env);
+      if (expr.op === 'not') {
+        if (operand.type !== 'Bool') throw new Error(`internal: 'not' on ${operand.type}`);
+        return { type: 'Bool', value: !operand.value };
+      }
       if (operand.type === 'Int') return { type: 'Int', value: -operand.value };
       if (operand.type === 'Float') return { type: 'Float', value: -operand.value };
       throw new Error(`internal: unary '-' on ${operand.type}`);
     }
-    case 'binary':
+    case 'binary': {
+      // 'and'/'or' short-circuit: the left operand alone can decide the
+      // result ('False and e' / 'True or e'), so 'e' is only evaluated
+      // when it's still needed — the same laziness every mainstream
+      // language gives its logical operators.
+      if (expr.op === 'and' || expr.op === 'or') {
+        const left = evaluateExpr(expr.left, env);
+        if (left.type !== 'Bool') throw new Error(`internal: '${expr.op}' on non-Bool`);
+        if (expr.op === 'and' ? !left.value : left.value) return left;
+        const right = evaluateExpr(expr.right, env);
+        if (right.type !== 'Bool') throw new Error(`internal: '${expr.op}' on non-Bool`);
+        return right;
+      }
       return evaluateBinary(expr.op, evaluateExpr(expr.left, env), evaluateExpr(expr.right, env));
+    }
     case 'block': {
       return evaluateBlock(expr, env);
     }

package/src/lexer/index.ts

@@ -114,13 +114,14 @@ export class Lexer {
       return this.readWord();
     }
 
-    // A leading-dot float like .5 looks like a number attempt, so L0002 is
-    // more helpful than L0001 ("unexpected character").
+    // A leading-dot float like .5 is a number missing its integer part, so
+    // L0004 (its own error, with a certain '0.5' fix) is more helpful than
+    // L0001 ("unexpected character") or L0002 (a number run into letters).
     if (ch === '.' && isDigit(this.c.peek(1))) {
       const start = this.c.mark();
       this.c.advance(); // '.'
       this.consumeWhile(isDigit);
-      return this.error('L0002', this.c.spanFrom(start));
+      return this.error('L0004', this.c.spanFrom(start));
     }
 
     const start = this.c.mark();

package/src/lexer/keywords.ts

@@ -3,6 +3,9 @@ import type { TokenKind } from './token.js';
 export const KEYWORDS: Record<string, TokenKind> = {
   div: 'KW_DIV',
   mod: 'KW_MOD',
+  and: 'KW_AND',
+  or: 'KW_OR',
+  not: 'KW_NOT',
   fix: 'KW_FIX',
   mut: 'KW_MUT',
   if: 'KW_IF',

package/src/lexer/token.ts

@@ -12,6 +12,9 @@ export type TokenKind =
   | 'SLASH'      // '/', always real division — yields a Float
   | 'KW_DIV'     // the keyword div — Int-only floor division
   | 'KW_MOD'     // the keyword mod — Int-only floored modulo
+  | 'KW_AND'     // the keyword and — Bool-only logical and, short-circuits
+  | 'KW_OR'      // the keyword or — Bool-only logical or, short-circuits
+  | 'KW_NOT'     // the keyword not — Bool-only prefix negation
   | 'KW_FIX'     // the keyword fix — declares a fixed slot
   | 'KW_MUT'     // the keyword mut — declares a mutable slot
   | 'KW_IF'      // the keyword if — starts a conditional expression
@@ -50,9 +53,24 @@ export interface Span {
   end: Position;   // exclusive — points one past the last character
 }
 
+// A supporting span a stage attaches to a marker — e.g. the earlier
+// declaration a "can't reassign" error refers back to. `key` names the span's
+// role; the matching label (prose) lives in the error's .yml row, keyed the
+// same way, so no stage holds a user-facing sentence.
+export interface RelatedMarker {
+  key: string;
+  span: Span;
+}
+
 export interface Marker {
   code: string;
   span: Span;
+  related?: RelatedMarker[];
+  // Named values a stage knows but the source can't reconstruct — chiefly the
+  // type names in a type error ('Int', 'String'). Interpolated into the
+  // message/explanation as {key}. Kept as strings so the checker never holds a
+  // sentence, only the words that fill the blanks.
+  data?: Record<string, string>;
 }
 
 export interface Token {

package/src/lib.ts

@@ -1,20 +1,25 @@
 // Public programmatic API for the Ascent language toolchain.
-// The `ascent` CLI (see index.ts) is the primary entry point, but the
-// individual stages are re-exported here so tools can embed the pipeline:
+// The `ascent` CLI (see index.ts) is the primary entry point. Embedders
+// wanting source-to-typed-AST in one call should use parse():
+//
+//   const { typedProgram, errorMarkers } = parse(src);
+//   const result = executeProgram(typedProgram!, new Environment());
+//
+// The individual stages are also re-exported for tools that need
+// intermediate results (e.g. tokens, or the untyped AST):
 //
 //   const { tokens, errorMarkers } = new Lexer(src).tokenize();
-//   const { program } = new Parser(tokens).parse();
+//   const { program } = parseTokens(tokens);
 //   const { typedProgram } = typecheck(program!);
-//   const result = executeProgram(typedProgram!, new Environment());
 
 export { Lexer } from './lexer/index.js';
 export type { LexResult } from './lexer/index.js';
 
-export { Parser } from './parser/index.js';
+export { parse, parseTokens } from './parser/index.js';
 export type { ParseResult } from './parser/index.js';
 
 export { typecheck } from './parser/typechecker.js';
-export type { TypeCheckResult } from './parser/typechecker.js';
+export type { TypedResult } from './parser/typechecker.js';
 
 export {
   Environment,
@@ -24,7 +29,7 @@ export {
 } from './interpreter.js';
 export type { RuntimeValue, AssignResult } from './interpreter.js';
 
-export { formatExpr, formatStmt, formatValue } from './parser/printer.js';
+export { formatExpr, formatStmt, formatValue, valueToString } from './parser/printer.js';
 export { formatTypedStmt } from './parser/typed-printer.js';
 
 export * from './types/types.js';

package/src/parser/ast.ts

@@ -2,9 +2,9 @@ import type { Span } from '../lexer/token.js';
 
 // TypeExpr is the AST node for a type written in source code.
 // It carries span information so the type checker can point at it in errors.
-export type TypeExpr =
-  | { kind: 'TypeName'; name: 'Int' | 'Float' | 'Bool' | 'String'; span: Span }
-  | { kind: 'ListType'; elem: TypeExpr; span: Span };
+export type TypeName = { kind: 'TypeName'; name: 'Int' | 'Float' | 'Bool' | 'String'; span: Span };
+export type ListType = { kind: 'ListType'; elem: TypeExpr; span: Span };
+export type TypeExpr = TypeName | ListType;
 
 export type Literal = (
   | { kind: 'literal'; valueType: 'Int'; value: bigint; span: Span }
@@ -15,10 +15,11 @@ export type Literal = (
   | { kind: 'literal'; valueType: 'Done'; span: Span }
 );
 
-export type UnaryOp = '-';
+export type UnaryOp = '-' | 'not';
 export type ArithmeticOp = '+' | '-' | '*' | '/' | 'div' | 'mod';
 export type ComparisonOp = '==' | '!=' | '<' | '<=' | '>' | '>=';
-export type BinaryOp = ArithmeticOp | ComparisonOp;
+export type BooleanOp = 'and' | 'or';
+export type BinaryOp = ArithmeticOp | ComparisonOp | BooleanOp;
 
 // A block is itself an expression — it yields the value of its last
 // statement, or Done when empty (the '{}' unit value).
@@ -53,7 +54,7 @@ export type Expr = (
 export type Statement = (
   | { kind: 'fix'; name: string; typeAnnotation: TypeExpr | null; init: Expr; span: Span }
   | { kind: 'mut'; name: string; typeAnnotation: TypeExpr | null; init: Expr; span: Span }
-  | { kind: 'assign'; name: string; value: Expr; span: Span }
+  | { kind: 'assign'; name: string; nameSpan: Span; value: Expr; span: Span }
   | { kind: 'expr'; expr: Expr; span: Span }
   | { kind: 'while'; cond: Expr; body: Block; span: Span }
 );

package/src/parser/expr.ts

@@ -22,14 +22,20 @@ import { parseBlock, parseIf } from './stmt.js';
 // This ladder is the single source of truth for what binds tighter
 // than what: postfix (`.method()`, `[index]`) binds tightest, then
 // unary '-', then '*'/'/'/'div'/'mod', then '+'/'-', then the
-// comparisons, loosest. Every table below is keyed off these numbers
+// comparisons, then 'not', then 'and', then 'or', loosest —
+// the word operators sit below the comparisons (§5 of design.md), so
+// `a == b and c == d` groups as `(a == b) and (c == d)`, never
+// `a == (b and c) == d`. Every table below is keyed off these numbers
 // instead of inlining its own.
 const BP = {
-  COMPARISON: 1,
-  ADDITIVE: 2,
-  MULTIPLICATIVE: 3,
-  UNARY: 4,
-  POSTFIX: 4,
+  OR: 1,
+  AND: 2,
+  NOT: 3,
+  COMPARISON: 4,
+  ADDITIVE: 5,
+  MULTIPLICATIVE: 6,
+  UNARY: 7,
+  POSTFIX: 7,
 } as const;
 
 // Every binary operator this parser knows about has one row in this
@@ -40,7 +46,12 @@ const BP = {
 // `(1 + 2) < (3 * 4)`. Comparisons are also marked `assoc: 'none'`:
 // unlike '+' or '*', two of them can never sit side by side
 // (`a < b < c` is rejected, not silently grouped one way or the other).
+// 'or' belongs to a tier below 'and' — the same "same precedence,
+// left-associative" shape as '+'/'-' — so `a or b or c` groups as
+// `(a or b) or c`.
 const INFIX_OPS: Partial<Record<TokenKind, { op: BinaryOp; bp: number; assoc: 'left' | 'none' }>> = {
+  KW_OR: { op: 'or', bp: BP.OR, assoc: 'left' },
+  KW_AND: { op: 'and', bp: BP.AND, assoc: 'left' },
   EQ_EQ: { op: '==', bp: BP.COMPARISON, assoc: 'none' },
   BANG_EQ: { op: '!=', bp: BP.COMPARISON, assoc: 'none' },
   LT: { op: '<', bp: BP.COMPARISON, assoc: 'none' },
@@ -66,12 +77,14 @@ const POSTFIX_OPS: Partial<Record<TokenKind, { bp: number }>> = {
   LBRACKET: { bp: BP.POSTFIX },
 };
 
-// Prefix table — unary '-' is the Pratt parser's other operator kind
-// (a "nud" that still takes an operand, parsed in parseAtom below).
-// Only one entry today, but its binding power is declared here rather
-// than inlined at the call site.
+// Prefix table — the Pratt parser's other operator kind (a "nud" that
+// still takes an operand, parsed in parseAtom below). Unary '-' binds
+// tight, at the same tier as postfix; 'not' binds much looser — tighter
+// than 'and'/'or' but looser than the comparisons — which is what makes
+// `not a == b` parse as `not (a == b)` rather than `(not a) == b`.
 const PREFIX_OPS: Partial<Record<TokenKind, { op: UnaryOp; bp: number }>> = {
   MINUS: { op: '-', bp: BP.UNARY },
+  KW_NOT: { op: 'not', bp: BP.NOT },
 };
 
 export function parseExpr(ts: TokenStream, minBp = 0): Expr | null {
@@ -152,12 +165,14 @@ function parseMethodCall(ts: TokenStream, receiver: Expr): Expr | null {
   ts.advance(); // consume method name
 
   if (ts.peek().kind !== 'LPAREN') {
-    ts.report('S0001', ts.peek().span);
+    // A missing '(' here is not an unclosed group — the call's argument list
+    // never opened — so it's its own error, not S0001.
+    ts.report('S0014', ts.peek().span);
     return null;
   }
-  ts.advance(); // consume '('
+  const openParen = ts.advance(); // consume '('
 
-  const parsed = ts.parseSeparated(() => parseExpr(ts), 'COMMA', 'RPAREN', 'S0001');
+  const parsed = ts.parseSeparated(() => parseExpr(ts), 'COMMA', 'RPAREN', 'S0001', false, openParen.span);
   if (parsed === null) return null;
 
   return {
@@ -171,12 +186,12 @@ function parseMethodCall(ts: TokenStream, receiver: Expr): Expr | null {
 
 // 'list[index]' — LBRACKET already confirmed on lookahead by the Pratt loop.
 function parseIndex(ts: TokenStream, list: Expr): Expr | null {
-  ts.advance(); // consume '['
+  const openBracket = ts.advance(); // consume '['
 
   const index = parseExpr(ts);
   if (index === null) return null;
 
-  const rbracket = ts.expect('RBRACKET', 'S0013');
+  const rbracket = ts.expect('RBRACKET', 'S0013', [{ key: 'opener', span: openBracket.span }]);
   if (rbracket === null) return null;
 
   return {
@@ -255,7 +270,7 @@ function parseAtom(ts: TokenStream): Expr | null {
     }
     const closing = ts.peek();
     if (closing.kind !== 'RPAREN') {
-      ts.report('S0001', closing.span);
+      ts.report('S0001', closing.span, [{ key: 'opener', span: tok.span }]);
       return null;
     }
     ts.advance(); // consume ')'
@@ -291,8 +306,8 @@ function parseAtom(ts: TokenStream): Expr | null {
 
 // 'name(arg, arg, …)' — callee token already consumed by parseAtom.
 function parseCall(ts: TokenStream, callee: Token): Expr | null {
-  ts.advance(); // consume '('
-  const parsed = ts.parseSeparated(() => parseExpr(ts), 'COMMA', 'RPAREN', 'S0001');
+  const openParen = ts.advance(); // consume '('
+  const parsed = ts.parseSeparated(() => parseExpr(ts), 'COMMA', 'RPAREN', 'S0001', false, openParen.span);
   if (parsed === null) return null;
 
   return {
@@ -306,7 +321,7 @@ function parseCall(ts: TokenStream, callee: Token): Expr | null {
 // '[' expr, expr, … ']' — list literal. Already peeked '[' in parseAtom.
 function parseList(ts: TokenStream): Expr | null {
   const openTok = ts.advance(); // consume '['
-  const parsed = ts.parseSeparated(() => parseExpr(ts), 'COMMA', 'RBRACKET', 'S0013');
+  const parsed = ts.parseSeparated(() => parseExpr(ts), 'COMMA', 'RBRACKET', 'S0013', false, openTok.span);
   if (parsed === null) return null;
 
   return { kind: 'list', elements: parsed.items, span: { start: openTok.span.start, end: parsed.close.span.end } };

package/src/parser/index.ts

@@ -1,50 +1,50 @@
 import type { Token, Marker } from '../lexer/token.js';
-import type { ArgDef, Program } from './ast.js';
+import { Lexer } from '../lexer/index.js';
+import type { Program } from './ast.js';
 import { TokenStream } from './token-stream.js';
 import { parseStmt } from './stmt.js';
-import { parseArgs } from './type-expr.js';
+import { parseArgsSection } from './type-expr.js';
+import { typecheck } from './typechecker.js';
+import type { TypedResult } from './typechecker.js';
 
 export interface ParseResult {
   program: Program | null;
   errorMarkers: Marker[];
 }
 
-// The program is an optional 'args (…);' header followed by a
-// semicolon-separated run of statements up to EOF — the same
-// "item (sep item)* close" shape as a block, with EOF standing in for
-// the closing brace. `recover` is on, so a malformed statement is
-// synchronized past rather than aborting the whole parse.
-function parseProgram(ts: TokenStream): Program | null {
-  let args: ArgDef[] = [];
-  if (ts.peek().kind === 'KW_ARGS') {
-    const result = parseArgs(ts);
-    if (result === null) return null;
-    args = result;
-
-    if (ts.expect('SEMICOLON', 'S0011') === null) return null;
+export const parseTokens = (tokens: Token[]): ParseResult => {
+  const ts = new TokenStream(tokens);
+  const args = parseArgsSection(ts);
+  if (args === null) {
+    return { program: null, errorMarkers: ts.errors };
   }
 
-  const parsed = ts.parseSeparated(() => parseStmt(ts), 'SEMICOLON', 'EOF', 'S0011', true);
-  if (parsed === null) return null;
+  const parsed = ts.parseSeparated(
+    () => parseStmt(ts), 'SEMICOLON', 'EOF', 'S0011', true
+  );
 
-  return { args, stmts: parsed.items };
-}
+  if (parsed === null) {
+    return { program: null, errorMarkers: ts.errors };
+  }
 
-// The parser's public entry point. Phase 5 moved the grammar into
-// free functions over a TokenStream (token-stream.ts, expr.ts, stmt.ts,
-// type-expr.ts); this class is the thin wiring that owns the stream for
-// one parse and exposes the same `new Parser(tokens).parse()` API the
-// rest of the toolchain calls.
-export class Parser {
-  private readonly tokens: Token[];
+  const program: Program = {
+    args,
+    stmts: parsed.items
+  };
 
-  public constructor(tokens: Token[]) {
-    this.tokens = tokens;
+  return { program, errorMarkers: ts.errors };
+}
+
+export const parse = (src: string): TypedResult => {
+  const lexResult = new Lexer(src).tokenize();
+  if (lexResult.errorMarkers.length > 0) {
+    return { typedProgram: null, errorMarkers: lexResult.errorMarkers };
   }
 
-  public parse(): ParseResult {
-    const ts = new TokenStream(this.tokens);
-    const program = parseProgram(ts);
-    return { program, errorMarkers: ts.errors };
+  const parseResult = parseTokens(lexResult.tokens);
+  if (parseResult.program === null || parseResult.errorMarkers.length > 0) {
+    return { typedProgram: null, errorMarkers: parseResult.errorMarkers };
   }
+
+  return typecheck(parseResult.program);
 }

package/src/parser/printer.ts

@@ -144,3 +144,25 @@ export const formatValue = (value: RuntimeValue): string => {
       return chalk.yellow('Done');
   }
 };
+
+export const valueToString = (value: RuntimeValue): string => {
+  switch (value.type) {
+    case 'Int':
+      return String(value.value);
+    case 'Float':
+      const floatStr = String(value.value);
+      return floatStr.includes('.') ? floatStr : floatStr + '.0';
+    case 'Bool':
+      return value.value ? 'True' : 'False';
+    case 'String':
+      return value.value;
+    case 'List': {
+      const items = value.elements.map(valueToString).join(', ');
+      return `[${items}]`;
+    }
+    case 'None':
+      return 'None';
+    case 'Done':
+      return 'Done';
+  }
+};

package/src/parser/stmt.ts

@@ -14,7 +14,7 @@ import { parseTypeExpr } from './type-expr.js';
 // this consumes its own.
 export function parseBlock(ts: TokenStream, openTok?: Token): Block | null {
   openTok ??= ts.advance(); // consume '{' unless already consumed
-  const parsed = ts.parseSeparated(() => parseStmt(ts), 'SEMICOLON', 'RBRACE', 'S0005', true);
+  const parsed = ts.parseSeparated(() => parseStmt(ts), 'SEMICOLON', 'RBRACE', 'S0005', true, openTok.span);
   if (parsed === null) return null;
 
   return { kind: 'block', stmts: parsed.items, span: { start: openTok.span.start, end: parsed.close.span.end } };
@@ -24,14 +24,15 @@ export function parseBlock(ts: TokenStream, openTok?: Token): Block | null {
 // The body braces already delimit the construct, but the test stays
 // parenthesized to match the C-family/TS surface (§5).
 function parseCond(ts: TokenStream): Expr | null {
-  if (ts.expect('LPAREN', 'S0006') === null) return null;
+  const open = ts.expect('LPAREN', 'S0006');
+  if (open === null) return null;
 
   const cond = parseExpr(ts);
   if (cond === null) {
     return null;
   }
 
-  if (ts.expect('RPAREN', 'S0001') === null) return null;
+  if (ts.expect('RPAREN', 'S0001', [{ key: 'opener', span: open.span }]) === null) return null;
 
   return cond;
 }
@@ -149,6 +150,7 @@ function parseAssign(ts: TokenStream): Statement | null {
   return {
     kind: 'assign',
     name: nameTok.value,
+    nameSpan: nameTok.span,
     value,
     span: { start: nameTok.span.start, end: value.span.end },
   };

package/src/parser/token-stream.ts

@@ -1,4 +1,4 @@
-import type { Token, TokenKind, Marker, Span } from '../lexer/token.js';
+import type { Token, TokenKind, Marker, RelatedMarker, Span } from '../lexer/token.js';
 
 // The token stream is everything the grammar productions in expr.ts,
 // stmt.ts and type-expr.ts share but that isn't grammar itself: the
@@ -39,17 +39,20 @@ export class TokenStream {
   // Record a diagnostic at a given span. The one place productions push
   // to the error log when they need to report something expect() can't
   // express (e.g. "this token was fine but the *next* thing is wrong").
-  public report(code: string, span: Span): void {
-    this.errors.push({ code, span });
+  public report(code: string, span: Span, related?: RelatedMarker[]): void {
+    const marker: Marker = { code, span };
+    if (related !== undefined && related.length > 0) marker.related = related;
+    this.errors.push(marker);
   }
 
   // Consume-or-diagnose: the shape every "expect this exact token here"
   // check in the grammar shares. Returns the consumed token, or records
-  // `code` at the offending token's span and returns null.
-  public expect(kind: TokenKind, code: string): Token | null {
+  // `code` at the offending token's span and returns null. `related` carries
+  // any supporting spans (e.g. the '(' this missing ')' should have closed).
+  public expect(kind: TokenKind, code: string, related?: RelatedMarker[]): Token | null {
     const tok = this.peek();
     if (tok.kind !== kind) {
-      this.report(code, tok.span);
+      this.report(code, tok.span, related);
       return null;
     }
     return this.advance();
@@ -87,12 +90,16 @@ export class TokenStream {
   // malformed statement doesn't take the rest of the file's diagnostics
   // down with it. The list can still come back null if synchronize()
   // runs all the way to EOF without ever finding `close`.
+  // `openSpan`, when given, is the span of the opening delimiter (the '(', '{'
+  // or '['); it rides along on the close-token error so an unclosed group can
+  // point back at where it opened.
   public parseSeparated<T>(
     parseItem: () => T | null,
     sep: TokenKind,
     close: TokenKind,
     closeCode: string,
     recover = false,
+    openSpan: Span | null = null,
   ): { items: T[]; close: Token } | null {
     const items: T[] = [];
     if (this.peek().kind !== close) {
@@ -111,10 +118,15 @@ export class TokenStream {
         items.push(item);
         if (this.peek().kind !== sep) break;
         this.advance(); // consume separator
-        if (this.peek().kind === close) break; // trailing separator
+        // Break on the close OR on end-of-input: a trailing separator right
+        // before EOF means the group is simply unclosed, so fall straight to
+        // the close-token error below instead of trying to parse another item
+        // (which would spuriously demand an expression at end of file).
+        if (this.peek().kind === close || this.peek().kind === 'EOF') break;
       }
     }
-    const closeTok = this.expect(close, closeCode);
+    const related: RelatedMarker[] = openSpan !== null ? [{ key: 'opener', span: openSpan }] : [];
+    const closeTok = this.expect(close, closeCode, related);
     if (closeTok === null) return null;
     return { items, close: closeTok };
   }

package/src/parser/type-expr.ts

@@ -50,14 +50,20 @@ function parseArgDef(ts: TokenStream): ArgDef | null {
   return { name: nameTok.value, type: typeTok.value as ArgType };
 }
 
-// 'args (name: Type, …)' — the program's typed input declaration.
-export function parseArgs(ts: TokenStream): ArgDef[] | null {
+// 'args (name: Type, …) ;' — the program's typed input declaration, if
+// present. Returns [] (not null) when there's no 'args' keyword at all;
+// null is reserved for an actual parse error.
+export function parseArgsSection(ts: TokenStream): ArgDef[] | null {
+  if (ts.peek().kind !== 'KW_ARGS') return [];
   ts.advance(); // consume 'args'
 
-  if (ts.expect('LPAREN', 'S0006') === null) return null;
+  const open = ts.expect('LPAREN', 'S0006');
+  if (open === null) return null;
 
-  const parsed = ts.parseSeparated(() => parseArgDef(ts), 'COMMA', 'RPAREN', 'S0001');
+  const parsed = ts.parseSeparated(() => parseArgDef(ts), 'COMMA', 'RPAREN', 'S0001', false, open.span);
   if (parsed === null) return null;
 
+  if (ts.expect('SEMICOLON', 'S0011') === null) return null;
+
   return parsed.items;
 }