docs: clarify RawStmt is a Node type but appears inline in ParseResult

- Update comments to reference protobuf 'repeated RawStmt' definition
- Clarify that RawStmt IS a Node type (in Node oneof)
- Explain why ParseResult.stmts contains RawStmt objects inline
- Add protobuf message definitions to ENTRY_POINT.md for clarity

Author: pyramation

ENTRY_POINT.md

@@ -44,11 +44,25 @@
 
 ### Key Clarification:
 
-The structure from libpg-query is:
+The structure from libpg-query is based on the protobuf definition:
+```protobuf
+message ParseResult {
+  int32 version = 1;
+  repeated RawStmt stmts = 2;  // "repeated" means array contains RawStmt inline
+}
+
+message RawStmt {
+  Node stmt = 1;
+  int32 stmt_location = 2;
+  int32 stmt_len = 3;
+}
+```
+
+This translates to:
 ```typescript
 ParseResult {
   version: number;
-  stmts: RawStmt[];  // Array of RawStmt objects directly (NOT wrapped)
+  stmts: RawStmt[];  // Array contains RawStmt objects inline (not wrapped as nodes)
 }
 
 // Each RawStmt in the array has this structure:
@@ -59,7 +73,7 @@ RawStmt {
 }
 ```
 
-This is different from wrapped nodes like `{ RawStmt: {...} }` which are used when explicitly creating a Node.
+Important: While RawStmt IS a Node type (listed in the Node oneof), when it appears in ParseResult.stmts, it's inline due to the "repeated RawStmt" protobuf definition. This is different from wrapped nodes like `{ RawStmt: {...} }` which are used when explicitly creating a Node for the deparser.
 
 ## Overview
 

packages/deparser/src/deparser.ts

@@ -18,7 +18,8 @@ export interface DeparserOptions {
 function isParseResult(obj: any): obj is t.ParseResult {
   // A ParseResult is an object that could have stmts (but not required)
   // and is not already wrapped as a Node
-  // IMPORTANT: ParseResult.stmts contains RawStmt objects directly (not wrapped)
+  // IMPORTANT: ParseResult.stmts is "repeated RawStmt" in protobuf, meaning
+  // the array contains RawStmt objects inline (not wrapped as { RawStmt: ... })
   // Example: { version: 170004, stmts: [{ stmt: {...}, stmt_len: 32 }] }
   return obj && typeof obj === 'object' && 
     !Array.isArray(obj) &&
@@ -38,7 +39,8 @@ function isWrappedParseResult(obj: any): obj is { ParseResult: t.ParseResult } {
  * Entry Points:
  * 1. ParseResult (from libpg-query) - The complete parse result
  *    Structure: { version: number, stmts: RawStmt[] }
- *    Note: stmts contains RawStmt objects directly, NOT wrapped as { RawStmt: ... }
+ *    Note: stmts is "repeated RawStmt" in protobuf, so array contains RawStmt 
+ *    objects inline (not wrapped as { RawStmt: ... } nodes)
  *    Example: { version: 170004, stmts: [{ stmt: {...}, stmt_len: 32 }] }
  * 
  * 2. Wrapped ParseResult - When explicitly wrapped as a Node
@@ -184,7 +186,7 @@ export class Deparser implements DeparserVisitor {
     }
 
     // Deparse each RawStmt in the ParseResult
-    // Note: node.stmts contains RawStmt objects directly (not wrapped)
+    // Note: node.stmts is "repeated RawStmt" so contains RawStmt objects inline
     // Each element has structure: { stmt: Node, stmt_len?: number, stmt_location?: number }
     return node.stmts
       .filter((rawStmt: t.RawStmt) => rawStmt != null)