Document flat parameter declaration and usage shapes

Agent-Logs-Url: https://github.com/dadhi/FastExpressionCompiler/sessions/cec4f4cc-6325-4330-b621-6a290f3fef7e

Co-authored-by: dadhi <39516+dadhi@users.noreply.github.com>

Author: Copilot

src/FastExpressionCompiler.LightExpression/FlatExpression.cs

@@ -338,6 +338,12 @@ public int Block(params int[] expressions) =>
     /// <summary>Adds a block node with optional explicit result type and variables.</summary>
     public int Block(Type type, IEnumerable<int> variables, params int[] expressions)
     {
+        // Block shape:
+        // - without variables: children = [body-expressions-child-list]
+        // - with variables: children = [declarations-child-list, body-expressions-child-list]
+        // The declarations child list contains parameter declaration nodes.
+        // Each declaration node is later bound to this block via ChildIdx = blockIndex and ChildCount = declaration position.
+        // Parameter references inside the body are separate usage nodes with ChildIdx = declaration index.
         if (expressions == null || expressions.Length == 0)
             throw new ArgumentException("Block should contain at least one expression.", nameof(expressions));
 
@@ -367,6 +373,10 @@ public int Lambda<TDelegate>(int body, params int[] parameters) where TDelegate
     /// <summary>Adds a lambda node.</summary>
     public int Lambda(Type delegateType, int body, params int[] parameters)
     {
+        // Lambda shape: children = [body, declaration0, declaration1, ...]
+        // The lambda stores declaration nodes directly after the body.
+        // Each declaration node is later bound to this lambda via ChildIdx = lambdaIndex and ChildCount = parameter position.
+        // Parameter references inside the body are separate usage nodes with ChildIdx = declaration index.
         if (parameters == null || parameters.Length == 0)
             return AddFactoryExpressionNode(delegateType, null, ExpressionType.Lambda, 0, body);
 
@@ -1259,6 +1269,9 @@ private void BindParameterDeclarations(int ownerIndex, in ChildList declarations
 
     private void BindParameterDeclaration(int ownerIndex, int declarationIndex, int position)
     {
+        // Parameter node contract:
+        // - declaration node: ParameterDeclarationFlag set, ChildIdx = owning lambda/block index, ChildCount = position in that owner
+        // - usage node: ParameterDeclarationFlag clear, ChildIdx = declaration node index, ChildCount = 0
         ref var declaration = ref Nodes.GetSurePresentRef(declarationIndex);
         if (!declaration.IsParameterDeclaration())
             Throw.ParameterDeclarationExpected(declarationIndex);