feat(ast/parser): add quantity slot to Let + ADR-007 hybrid surface syntax

Adds el_quantity to ExprLet and sl_quantity to StmtLet, then threads
two surface forms through the parser per ADR-007 (META.a2ml):

- Option C primary: @linear / @Erased / @unrestricted attribute prefix.
  Wired into let_decl, stmt_let, lambda_param, and param.
- Option B sugar: :1 / :0 / :ω numeric annotation after the binder.
  Wired into let_decl and stmt_let only. Sugar form on params is
  deferred — would require repositioning the existing qty? slot.

Both surface forms parse to the same internal slot. Unknown
@-attribute names and integer literals outside {0, 1} are rejected
at parse time via Parser_errors.Parse_action_error, a new shared
exceptions module that bridges the parser.mly prologue (where
Menhir doesn't expose user exceptions through .mli) to parse_driver
without circular dependency.

Adds parser_errors to the dune modules list.

Mechanical pattern-update sweep across julia_codegen, desugar_traits,
typecheck, and sexpr_dump for the new record fields. Build clean,
test baseline unchanged at this point (this commit is semantically
no-op for enforcement; the scaling logic and fixtures land in the
next commit).

Refs ADR-007, ADR-002.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

lib/ast.ml

@@ -104,6 +104,14 @@ type expr =
   | ExprVar of ident
   | ExprLet of {
       el_mut : bool;
+      el_quantity : quantity option;
+        (** QTT binder quantity, per ADR-002 / ADR-007.
+            None means: defaults to QOmega (unrestricted), the
+            unannotated case. The quantity scales the value context
+            in the typing rule q·Γ₁ + Γ₂ ⊢ let x :^q = e1 in e2.
+            Surface syntaxes that populate this:
+            - @linear / @erased / @unrestricted (Option C, primary)
+            - :1 / :0 / :ω                       (Option B, sugar) *)
       el_pat : pattern;
       el_ty : type_expr option;
       el_value : expr;
@@ -170,6 +178,10 @@ and block = {
 and stmt =
   | StmtLet of {
       sl_mut : bool;
+      sl_quantity : quantity option;
+        (** QTT binder quantity for statement-position let, per
+            ADR-002 / ADR-007. None defaults to QOmega. Same surface
+            syntaxes as ExprLet's el_quantity. *)
       sl_pat : pattern;
       sl_ty : type_expr option;
       sl_value : expr;

lib/desugar_traits.ml

@@ -112,9 +112,10 @@ let rec desugar_expr (ctx : context) (expr : expr) : expr =
       elam_body = desugar_expr ctx elam_body;
     }
 
-  | ExprLet { el_mut; el_pat; el_ty; el_value; el_body } ->
+  | ExprLet { el_mut; el_quantity; el_pat; el_ty; el_value; el_body } ->
     ExprLet {
       el_mut;
+      el_quantity;
       el_pat;
       el_ty;
       el_value = desugar_expr ctx el_value;
@@ -178,9 +179,10 @@ and desugar_block (ctx : context) (blk : block) : block =
 
 and desugar_stmt (ctx : context) (stmt : stmt) : stmt =
   match stmt with
-  | StmtLet { sl_mut; sl_pat; sl_ty; sl_value } ->
+  | StmtLet { sl_mut; sl_quantity; sl_pat; sl_ty; sl_value } ->
     StmtLet {
       sl_mut;
+      sl_quantity;
       sl_pat;
       sl_ty;
       sl_value = desugar_expr ctx sl_value;

lib/dune

@@ -2,7 +2,7 @@
  (name affinescript)
  (public_name affinescript)
  (modes byte native)
- (modules ast codegen codegen_gc desugar_traits effect error error_collector error_formatter formatter interp julia_codegen json_output lexer linter module_loader opt parse_driver parse parser quantity resolve span symbol token trait typecheck types unify value wasm wasm_encode wasm_gc wasm_gc_encode wasi_runtime)
+ (modules ast codegen codegen_gc desugar_traits effect error error_collector error_formatter formatter interp julia_codegen json_output lexer linter module_loader opt parse_driver parse parser parser_errors quantity resolve span symbol token trait typecheck types unify value wasm wasm_encode wasm_gc wasm_gc_encode wasi_runtime)
  (libraries str unix sedlex fmt menhirLib yojson)
  (preprocess
   (pps ppx_deriving.show ppx_deriving.eq ppx_deriving.ord sedlex.ppx)))

lib/julia_codegen.ml

@@ -132,7 +132,7 @@ let rec gen_expr ctx (expr : expr) : string =
           "(if " ^ cond_str ^ "; " ^ then_str ^ "; else " ^ else_str ^ "; end)"
       | None ->
           "(if " ^ cond_str ^ "; " ^ then_str ^ "; end)")
-  | ExprLet { el_pat; el_value; el_body; el_mut = _; el_ty = _ } ->
+  | ExprLet { el_pat; el_value; el_body; el_mut = _; el_quantity = _; el_ty = _ } ->
       (* Let binding: 'local x = val; body' *)
       let pat_str = gen_pattern ctx el_pat in
       let val_str = gen_expr ctx el_value in
@@ -227,7 +227,7 @@ and gen_pattern_cond _ctx scrutinee pat =
 and gen_stmt ctx (stmt : stmt) : string =
   (* Statements (for blocks) *)
   match stmt with
-  | StmtLet { sl_pat; sl_value; sl_mut = _; sl_ty = _ } ->
+  | StmtLet { sl_pat; sl_value; sl_mut = _; sl_quantity = _; sl_ty = _ } ->
       let pat_str = gen_pattern ctx sl_pat in
       let val_str = gen_expr ctx sl_value in
       pat_str ^ " = " ^ val_str

lib/parse_driver.ml

@@ -165,6 +165,17 @@ let parse_string ~file content =
                    offset = pos.pos_cnum }
       in
       raise (Parse_error ("Syntax error", span))
+  | Parser_errors.Parse_action_error (msg, startpos, endpos) ->
+      let span = Span.make
+        ~file
+        ~start_pos:{ Span.line = startpos.Lexing.pos_lnum;
+                     col = startpos.pos_cnum - startpos.pos_bol + 1;
+                     offset = startpos.pos_cnum }
+        ~end_pos:{ Span.line = endpos.Lexing.pos_lnum;
+                   col = endpos.pos_cnum - endpos.pos_bol + 1;
+                   offset = endpos.pos_cnum }
+      in
+      raise (Parse_error (msg, span))
 
 (** Parse a program from a file *)
 let parse_file filename =
@@ -196,3 +207,14 @@ let parse_expr ~file content =
                    offset = pos.pos_cnum }
       in
       raise (Parse_error ("Syntax error", span))
+  | Parser_errors.Parse_action_error (msg, startpos, endpos) ->
+      let span = Span.make
+        ~file
+        ~start_pos:{ Span.line = startpos.Lexing.pos_lnum;
+                     col = startpos.pos_cnum - startpos.pos_bol + 1;
+                     offset = startpos.pos_cnum }
+        ~end_pos:{ Span.line = endpos.Lexing.pos_lnum;
+                   col = endpos.pos_cnum - endpos.pos_bol + 1;
+                   offset = endpos.pos_cnum }
+      in
+      raise (Parse_error (msg, span))

lib/parser.mly

@@ -182,9 +182,44 @@ quantity:
   | ONE { QOne }
   | OMEGA { QOmega }
 
+(* ADR-007 Option C — primary attribute form for quantity annotations.
+   `@linear` ≡ QOne, `@erased` ≡ QZero, `@unrestricted` ≡ QOmega.
+   Rejects unknown attribute names with a parse error. *)
+quantity_attr:
+  | AT name = lower_ident
+    { match name with
+      | "linear" -> QOne
+      | "erased" -> QZero
+      | "unrestricted" -> QOmega
+      | other ->
+        let msg = Printf.sprintf
+          "unknown quantity attribute '@%s'; expected @linear, @erased, or @unrestricted"
+          other in
+        raise (Parser_errors.Parse_action_error (msg, $startpos, $endpos)) }
+
+(* ADR-007 Option B — sugar form for quantity annotations on let/stmt_let.
+   Reads as `:1`, `:0`, or `:ω` immediately after the pattern. The lexer
+   emits INT for `0` and `1`, so we accept INT here and validate the value
+   at parse time, rejecting any integer outside {0, 1}. OMEGA is the
+   `omega` keyword or `ω` codepoint. *)
+quantity_b_sugar:
+  | COLON n = INT
+    { match n with
+      | 0 -> QZero
+      | 1 -> QOne
+      | other ->
+        let msg = Printf.sprintf
+          "invalid quantity literal '%d'; expected 0, 1, or ω (omega)"
+          other in
+        raise (Parser_errors.Parse_action_error (msg, $startpos, $endpos)) }
+  | COLON OMEGA { QOmega }
+
 param:
   | qty = quantity? own = ownership? name = ident COLON ty = type_expr
     { { p_quantity = qty; p_ownership = own; p_name = name; p_ty = ty } }
+  (* ADR-007 Option C: @linear x: Int *)
+  | qty_attr = quantity_attr own = ownership? name = ident COLON ty = type_expr
+    { { p_quantity = Some qty_attr; p_ownership = own; p_name = name; p_ty = ty } }
 
 ownership:
   | OWN { Own }
@@ -383,7 +418,8 @@ expr:
 
 expr_assign:
   | lhs = expr_or EQ rhs = expr_assign
-    { ExprLet { el_mut = false; el_pat = PatVar (mk_ident "_" $startpos(lhs) $endpos(lhs));
+    { ExprLet { el_mut = false; el_quantity = None;
+                el_pat = PatVar (mk_ident "_" $startpos(lhs) $endpos(lhs));
                 el_ty = None; el_value = lhs; el_body = Some rhs } }
   | e = expr_or { e }
 
@@ -499,9 +535,19 @@ expr_primary:
   | MATCH scrutinee = expr LBRACE arms = list(match_arm) RBRACE
     { ExprMatch { em_scrutinee = scrutinee; em_arms = arms } }
 
-  /* Let expressions */
+  /* Let expressions — ADR-007 hybrid surface syntax for quantities.
+     Four production paths cover the cross product of {C-attr, B-sugar, neither}
+     × {with type, without type}. The C-attribute form (`@linear let x = e`)
+     and the B-sugar form (`let x :1 = e`) cannot both appear on the same let
+     binder; they are alternative spellings, not stackable annotations. */
   | LET mut_ = MUT? pat = pattern ty = type_annotation? EQ value = expr
-    { ExprLet { el_mut = Option.is_some mut_; el_pat = pat;
+    { ExprLet { el_mut = Option.is_some mut_; el_quantity = None; el_pat = pat;
+                el_ty = ty; el_value = value; el_body = None } }
+  | qty_attr = quantity_attr LET mut_ = MUT? pat = pattern ty = type_annotation? EQ value = expr
+    { ExprLet { el_mut = Option.is_some mut_; el_quantity = Some qty_attr; el_pat = pat;
+                el_ty = ty; el_value = value; el_body = None } }
+  | LET mut_ = MUT? pat = pattern qty = quantity_b_sugar ty = type_annotation? EQ value = expr
+    { ExprLet { el_mut = Option.is_some mut_; el_quantity = Some qty; el_pat = pat;
                 el_ty = ty; el_value = value; el_body = None } }
 
   /* Lambda */
@@ -548,6 +594,11 @@ lambda_param:
                      p_ty = TyHole } }
   | name = ident COLON ty = type_expr
     { { p_quantity = None; p_ownership = None; p_name = name; p_ty = ty } }
+  /* ADR-007 Option C: @linear x or @linear x: Type */
+  | qty_attr = quantity_attr name = ident
+    { { p_quantity = Some qty_attr; p_ownership = None; p_name = name; p_ty = TyHole } }
+  | qty_attr = quantity_attr name = ident COLON ty = type_expr
+    { { p_quantity = Some qty_attr; p_ownership = None; p_name = name; p_ty = ty } }
 
 match_arm:
   | pat = pattern guard = match_guard? FAT_ARROW body = expr COMMA?
@@ -622,7 +673,14 @@ stmt_list_nonempty_trailing_expr:
 
 stmt:
   | LET mut_ = MUT? pat = pattern ty = type_annotation? EQ value = expr SEMICOLON
-    { StmtLet { sl_mut = Option.is_some mut_; sl_pat = pat; sl_ty = ty; sl_value = value } }
+    { StmtLet { sl_mut = Option.is_some mut_; sl_quantity = None;
+                sl_pat = pat; sl_ty = ty; sl_value = value } }
+  | qty_attr = quantity_attr LET mut_ = MUT? pat = pattern ty = type_annotation? EQ value = expr SEMICOLON
+    { StmtLet { sl_mut = Option.is_some mut_; sl_quantity = Some qty_attr;
+                sl_pat = pat; sl_ty = ty; sl_value = value } }
+  | LET mut_ = MUT? pat = pattern qty = quantity_b_sugar ty = type_annotation? EQ value = expr SEMICOLON
+    { StmtLet { sl_mut = Option.is_some mut_; sl_quantity = Some qty;
+                sl_pat = pat; sl_ty = ty; sl_value = value } }
   | e = expr SEMICOLON { StmtExpr e }
   | IF cond = expr then_blk = block else_part = else_part?
     { StmtExpr (ExprIf { ei_cond = cond; ei_then = ExprBlock then_blk; ei_else = else_part }) }

lib/parser_errors.ml

@@ -0,0 +1,18 @@
+(* SPDX-License-Identifier: PMPL-1.0-or-later *)
+(* SPDX-FileCopyrightText: 2024-2026 Jonathan D.A. Jewell (hyperpolymath) *)
+
+(** Shared exceptions for parser semantic actions.
+
+    This module exists because exceptions defined in the [%{ %}] prologue
+    of [parser.mly] are not exported through [parser.mli], so consumers
+    (notably [parse_driver.ml]) cannot pattern-match on them. Defining the
+    exception here lets both [parser.mly] and [parse_driver.ml] reference
+    it without a circular dependency. *)
+
+(** Raised by a parser semantic action when a syntactically valid form
+    carries a value the action rejects (e.g. a quantity literal that is
+    neither 0 nor 1, an unknown [@]-attribute name).
+
+    Caught by [Parse_driver] and translated to its [Parse_error]
+    exception with proper [Span.t] resolution. *)
+exception Parse_action_error of string * Lexing.position * Lexing.position

lib/sexpr_dump.ml

@@ -171,8 +171,14 @@ and literal_to_sexpr = function
 let rec expr_to_sexpr d = function
   | ExprLit lit       -> literal_to_sexpr lit
   | ExprVar id        -> id.name
-  | ExprLet { el_mut; el_pat; el_ty; el_value; el_body } ->
+  | ExprLet { el_mut; el_quantity; el_pat; el_ty; el_value; el_body } ->
     let tag = if el_mut then "let-mut" else "let" in
+    let q_str = match el_quantity with
+      | None -> ""
+      | Some QZero -> " #@erased"
+      | Some QOne -> " #@linear"
+      | Some QOmega -> " #@unrestricted"
+    in
     let ty_str = match el_ty with
       | None -> ""
       | Some t -> Printf.sprintf " : %s" (type_expr_to_sexpr t)
@@ -181,7 +187,7 @@ let rec expr_to_sexpr d = function
       | None -> ""
       | Some b -> Printf.sprintf "\n%s%s" (indent (d + 2)) (expr_to_sexpr (d + 2) b)
     in
-    Printf.sprintf "(%s %s%s %s%s)" tag
+    Printf.sprintf "(%s%s %s%s %s%s)" tag q_str
       (pattern_to_sexpr el_pat) ty_str (expr_to_sexpr (d + 2) el_value) body_str
   | ExprIf { ei_cond; ei_then; ei_else } ->
     let else_str = match ei_else with
@@ -298,13 +304,19 @@ and block_to_sexpr d blk =
 
 (** Convert a statement to S-expression form. *)
 and stmt_to_sexpr d = function
-  | StmtLet { sl_mut; sl_pat; sl_ty; sl_value } ->
+  | StmtLet { sl_mut; sl_quantity; sl_pat; sl_ty; sl_value } ->
     let tag = if sl_mut then "let-mut" else "let" in
+    let q_str = match sl_quantity with
+      | None -> ""
+      | Some QZero -> " #@erased"
+      | Some QOne -> " #@linear"
+      | Some QOmega -> " #@unrestricted"
+    in
     let ty_str = match sl_ty with
       | None -> ""
       | Some t -> Printf.sprintf " : %s" (type_expr_to_sexpr t)
     in
-    Printf.sprintf "(%s %s%s %s)" tag
+    Printf.sprintf "(%s%s %s%s %s)" tag q_str
       (pattern_to_sexpr sl_pat) ty_str (expr_to_sexpr (d + 2) sl_value)
   | StmtExpr e -> expr_to_sexpr d e
   | StmtAssign (lhs, op, rhs) ->

lib/typecheck.ml

@@ -573,7 +573,7 @@ let rec synth (ctx : context) (expr : expr) : ty result =
     lookup_var ctx name
 
   (* Let bindings: let pat = e1 in e2 *)
-  | ExprLet { el_pat; el_ty; el_value; el_body; el_mut = _ } ->
+  | ExprLet { el_pat; el_ty; el_value; el_body; el_mut = _; el_quantity = _ } ->
     (* Synthesize or check the value *)
     enter_level ctx;
     let* val_ty = begin match el_ty with
@@ -905,7 +905,7 @@ and synth_block (ctx : context) (blk : block) : ty result =
 
 and check_stmt (ctx : context) (stmt : stmt) : unit result =
   match stmt with
-  | StmtLet { sl_pat; sl_ty; sl_value; sl_mut = _ } ->
+  | StmtLet { sl_pat; sl_ty; sl_value; sl_mut = _; sl_quantity = _ } ->
     enter_level ctx;
     let* val_ty = begin match sl_ty with
       | Some te ->