[PR] State the rules a reader follows on the format pages [skywalking-ai-sessionizer]

["wu-sheng (via GitHub)" <gi...@apache.org>]

wu-sheng opened a new pull request, #47:
URL: https://github.com/apache/skywalking-ai-sessionizer/pull/47

   ## Why
   
   The formats are JSON lines and JSON. A reader in another language, such as the SkyWalking OAP, builds the same `asz.view` document from the same files. Where the pages did not state a rule, such a reader had to find it in asz's Go code, and ended up copying what Go's libraries do: how Go decodes a null inside a list, which integer type a field has, how it trims white space, how it rounds a time to milliseconds, and how it orders map keys. The pages now state these rules, so a reader follows the pages and never the code.
   
   ## What changes
   
   Documentation only. No code, key or format changes; the formats stay `sd/1`, `sf/1` and `asz.view` 1.0.
   
   - **Session Data, "Reading a record"**: the type of every record field, of every part field, of every dropped entry field, and of the `usage` values. A null is a field left out, and a reader ignores a field the page does not list, so a later version can add one. An integer is a whole number that fits in 64 bits with its sign, and `ord` and `off` are never negative. asz's reader stops at a line it cannot decode, as at a line that is not JSON. A `time` is RFC 3339 with a four-digit year, and times compare as the instants they name, with examples where the text order is the reverse. A reader does not have to copy what asz's code does with input asz never writes.
   - **Session Flow**: `attrs` keys are written sorted, and ids and keys sort in code point order, which the page defines. The rejection list gains the `provider_bodies` rule that `ProviderBodiesOf` already applies, with null read as no bodies.
   - **asz.view**: times round down to the millisecond; a round header's time is null when absent and 0 when it is not a time; ids compare in code point order; `attrs` are as the round wrote them; a data part's text is the record's readable text when it has one, a queued command's prompt included, and otherwise the data as written; white space is Unicode's `White_Space` property; which records give a call its `result`, `result_state`, `result_bytes` and `failed`; `request_to_result_ms` drops the rest of a millisecond.
   
   Each statement was checked against the code on `main`: `pkg/sessiondata` (`Record`, `Part`, `Drop`, `Usage`, `Reader.Next` and its callers in `internal/view`), `pkg/sessionflow` (`ProviderBodiesOf`, `checkRefs`, the frame sort) and `internal/view` (`Millis`, `millisPtr`, `durationMillis`, `fill`, `fillResult`, `readable`, `withoutProviderBodies`, `shortName`). GPT-6 reviewed the pages against that code in two rounds; its three findings on them are fixed.
   
   ## Tests
   
   `make check` passes.
   


-- 
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: notifications-unsubscribe@skywalking.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] State the rules a reader follows on the format pages [skywalking-ai-sessionizer]

["wu-sheng (via GitHub)" <gi...@apache.org>]

wu-sheng merged PR #47:
URL: https://github.com/apache/skywalking-ai-sessionizer/pull/47


-- 
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: notifications-unsubscribe@skywalking.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org