#71: Document v2 runner architecture

[tkilias]

Fixes #71

Summary

• document the v2 runner composition, lifecycle, ownership, shutdown, and namespace boundaries;
• define the worker-facing Context, Call, control-stream, message builder, and message view contracts;
• document Arrow C Data Interface ownership and composite call messages;
• define the two-queue background I/O implementation, eventfd/socket event loop, vectorized I/O, flow control, and row-boundary batch splitting;
• add architecture diagrams and protocol design references.

Protocol details

• the first record batch in each direction may be sent before Next; later batches use Next flow-control credit;
• background splitting targets approximately 4 MiB at row boundaries and permits oversized rows;
• orderly CloseConnection waits for the peer reply before transport close;
• terminal worker operations return the documented Result statuses.

Validation

• runner Markdown links and anchors validated;
• JSON schemas parsed successfully;
• conflict resolution completed against origin/main;
• GitHub Bazel, SLC-CI, fuzzing, and mutation-testing checks are running on this revision.

The PR is documentation/design-only; no production runner implementation is included.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-26T19:37:55.977175Z	d8a0d2d	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d8a0d2d745

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud