kshitijprasaddev opened a new pull request, #54987: URL: https://github.com/apache/arrow/pull/54987
### Rationale for this change The encapsulated message's `metadata_size` excludes its framing prefix, whereas the file footer's `Block.metaDataLength` includes it. The current `Block.offset` comment also suggests an offset past the message header, while the writer records the start of the encapsulated message. This ambiguity makes implementing an IPC reader or writer harder. Closes #47824. ### What changes are included in this PR? Clarify `Block.offset` and `Block.metaDataLength` in `format/File.fbs`, and explain the distinction in the columnar format documentation. Modern framing has `metaDataLength = 8 + metadata_size`; legacy framing without the continuation indicator uses `4 + metadata_size`. The body starts at `offset + metaDataLength`. ### Are these changes tested? - Checked the comments against `PayloadFileWriter::WritePayload`, `WriteMessage`, and the reader's block-offset handling in the current C++ sources. - Generated eight real IPC files with PyArrow 26.0.0: modern/legacy framing, primitive/dictionary arrays, and one/two record batches. Parsed the actual FlatBuffers footers with the Python FlatBuffers runtime and verified all 16 dictionary/record-batch blocks: prefix bytes at the stored offset, metadata-length equations, exact body start/bytes, and batch roundtrips. - `sphinx-lint --enable all --disable dangling-hyphen,line-too-long docs/source/format/Columnar.rst` passed with the repository-pinned sphinx-lint 0.9.1. - `git diff --check` passed. Compared File.fbs before/after with comment lines removed: schema declarations are unchanged. - No full Sphinx documentation build, C++ build, or upstream test-suite run is claimed. ### Are there any user-facing changes? Documentation and schema comments only; no schema layout, serialized format, or API changes. ### Was AI used for this PR? Codex investigated the issue, drafted the documentation and PR text, reviewed the diff against the implementation, and ran the local validation described above. Human review is pending. **PR code and description written by:** - [ ] Human - [x] AI **Reviewed before submission by:** - [ ] Human - [x] AI - [ ] Not reviewed -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
