Approve the actor and codec-driver boundary (10.1.3)

[lodyai]

Summary

Roadmap item 10.1.3 is complete. This PR accepts ADR 010: transport-frame boundary for zero-copy so that Vec<u8> bridges leave the core runtime deliberately in phase 11 rather than incidentally.

Implemented documentation changes:

• moved ADR 010 from Proposed to Accepted, with dual proposed/accepted dates;
• resolved the protocol-hook, Vec<u8> bridge, and serializable-packet-trait decisions in place;
• recorded the production FrameCodec::wrap_payload call-site inventory and deferred guard coverage to roadmap item 11.2.3;
• marked roadmap item 10.1.3 and zero-copy migration item 1.1.3 complete;
• aligned the inventory, developers' guide, documentation index, and ExecPlan with the accepted decision.

Decision outcome

ADR 010 adopts Option B:

1. Protocol hooks stay packet-oriented and run against Envelope before serialization. The known app-router before_send gap is documented and tracked under 11.2.1.
2. No public actor-boundary Vec<u8> compatibility shim is introduced. Packet for Vec<u8> remains test-only, and public CorrelatableFrame for Vec<u8> removal is sequenced with 11.2.2 / 14.2.1.
3. No new "serializable packet" trait is added; Packet plus EncodeWith<Serializer> already expresses the requirement.

Validation

• make markdownlint
• make check-fmt
• make lint
• make test
• coderabbit review --agent completed with findings: 0

References

• Roadmap item 10.1.3 in docs/roadmap.md
• ADR 010
• ExecPlan
• Lody session: https://lody.ai/leynos/sessions/b66e78e2-be51-4d80-a41f-a58cc41c2cc9

[sourcery-ai]

Sorry @LodyAI[bot], you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

The PR accepts ADR 010, defines the zero-copy actor and codec-driver boundary, documents compatibility rules and implementation guidance, adds the associated ExecPlan, and marks the relevant roadmap entries complete.

Changes

Zero-copy transport boundary documentation

Layer / File(s)	Summary
ADR acceptance and boundary outcome docs/adr-010-transport-frame-boundary-for-zero-copy.md	Update the ADR to Accepted and record transport-frame ownership, protocol-hook placement, migration sequencing, call-site guards, risks, and Vec<u8> bridge decisions.
Guidance and inventory alignment docs/developers-guide.md, docs/frame-vec-u8-inventory.md	Document the actor and codec-driver split, packet-oriented hooks, and test-only compatibility scope.
ExecPlan and roadmap closure docs/execplans/10-1-3-approve-actor-and-codec-driver-boundary.md, docs/contents.md, docs/roadmap.md, docs/zero-copy-frame-and-payload-migration-roadmap.md	Add the completed ExecPlan, index it, and mark the related roadmap checkpoints complete.

Suggested labels: Roadmap

Suggested reviewers: codescene-access

Poem

Accept the frame, the boundary bright,
Let actor packets take their flight.
Codec owns the bytes’ parade,
Roadmap ticks the plans as made.
Vec<u8> waits beyond the door—
Zero-copy charts the course once more.

🚥 Pre-merge checks | ✅ 20

✅ Passed checks (20 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title matches the PR scope and includes the required roadmap item reference 10.1.3.
Description check	✅ Passed	The description clearly describes the ADR acceptance and related documentation updates in this changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Testing (Overall)	✅ Passed	PASS: the PR only changes documentation; git diff shows no source or test code, so there are no new behavioural changes needing test coverage.
User-Facing Documentation	✅ Passed	No user-facing functionality changed; the PR only updates internal docs, and docs/users-guide.md already covers codecs, zero-copy payloads, packets, and hooks.
Developer Documentation	✅ Passed	Mark PASS: docs/developers-guide.md documents the boundary, ADR 010 is Accepted, roadmap items 10.1.3 and 1.1.3 are checked, and the execplan is marked COMPLETE.
Module-Level Documentation	✅ Passed	PASS: The PR only changes a Markdown execplan; no source modules are added or edited, so the module-docstring rule is not applicable.
Testing (Unit And Behavioural)	✅ Passed	PASS: The commit is docs-only and changes only the ExecPlan; no source, API, or behaviour changed, so unit or behavioural test additions are not applicable.
Testing (Property / Proof)	✅ Passed	Docs-only ExecPlan edit; no runtime invariant or proof obligation was introduced, so property/proof testing is not applicable.
Testing (Compile-Time / Ui)	✅ Passed	PASS: Treat this as docs-only; no Rust/TS code or UI output changed, so trybuild/snapshot tests are not applicable.
Unit Architecture	✅ Passed	PASS: the only changed file is a docs ExecPlan; no runtime units, dependencies, commands, queries, or tests were modified, so this architecture check is not applicable.
Domain Architecture	✅ Passed	PR diff touches only markdown docs; no source files or domain code were changed.
Observability	✅ Passed	Docs-only changes; no runtime code, logging, metrics, tracing, or alerting changes were introduced, so the observability bar is not triggered.
Security And Privacy	✅ Passed	PASS: the PR is docs-only, and scans found no secrets, creds, /home or /Users paths, or reviewer metadata; only benign /tmp log paths remain.
Performance And Resource Use	✅ Passed	Approve it: the PR changes only documentation, with no runtime code, loops, I/O, allocations, or hot-path behaviour altered.
Concurrency And State	✅ Passed	Documentation-only edits; no shared state, async tasks, locks, or ordering code were introduced.
Architectural Complexity And Maintainability	✅ Passed	The PR is documentation-only and documents an existing boundary; it adds no new code abstractions, layers, traits, registries, or hidden orchestration.
Rust Compiler Lint Integrity	✅ Passed	Only markdown docs changed; no Rust code, lint suppressions, or clone-heavy code was introduced.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 10-1-3-approve-actor-and-codec-driver-boundary

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/contents.md`:
- Around line 52-53: The sibling entry wording is inconsistent because the
`10.1.3` link description in `contents.md` is missing the “Completed” prefix.
Update the markdown entry for `Approve actor and codec-driver boundary` so the
visible description matches the completed-state phrasing used by the `10.1.1`
sibling entry, keeping the same link target and aligning the text in the table
of contents.

In `@docs/developers-guide.md`:
- Around line 48-49: Use en-GB-oxendict spelling in the developers guide: update
the “serialization” wording in the sentence about the codec driver and
FrameCodec::wrap_payload to “serialisation” so it matches the project’s spelling
convention; leave the rest of the sentence unchanged and verify only the
noncompliant occurrence in that paragraph.

In `@docs/execplans/10-1-3-approve-actor-and-codec-driver-boundary.md`:
- Line 155: The ExecPlan uses non-Oxford spellings that conflict with the
en-GB-oxendict style guide; update the affected documentation text in this
markdown file by replacing each -ise form with the corresponding -ize form. In
the ExecPlan content, change the wording around the roadmap completion note and
the other referenced sentences so the spellings in the relevant paragraphs use
finalize, finalizing, parallelize, and parameterizes consistently throughout.

In `@docs/frame-vec-u8-inventory.md`:
- Around line 351-356: The docs text in the frame-vec-u8 inventory note says the
app-router `before_send` gap is “tracked separately” but does not point readers
to the actual tracking item. Update the surrounding wording in this note to
include a direct link or parenthetical citation to the relevant roadmap entry,
issue, or ADR, using the existing `before_send` mention and nearby `roadmap.md`
reference as the anchor so contributors can navigate to the tracking source.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: a5e74d78-0464-455c-b0d7-516ca033ab38

📥 Commits

Reviewing files that changed from the base of the PR and between 3969c3b and ad5eb46.

📒 Files selected for processing (7)

• docs/adr-010-transport-frame-boundary-for-zero-copy.md
• docs/contents.md
• docs/developers-guide.md
• docs/execplans/10-1-3-approve-actor-and-codec-driver-boundary.md
• docs/frame-vec-u8-inventory.md
• docs/roadmap.md
• docs/zero-copy-frame-and-payload-migration-roadmap.md

[leynos]

@coderabbitai Have the following now been resolved?

❌ Failed checks (1 error)

Check name	Status	Explanation	Resolution
Security And Privacy	❌ Error	ExecPlan exposes an absolute /home/leynos/.lody/... path and planning-agent metadata, leaking internal operational details in docs.	Replace absolute local paths and agent/session metadata with relative repo paths or generic wording; keep execution notes non-identifying or private.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo '== ExecPlan outline =='
ast-grep outline docs/execplans/10-1-3-approve-actor-and-codec-driver-boundary.md --items all || true

echo '== Absolute home-path markers in changed documentation =='
rg -n -i -C 3 \
  '(/home/|/Users/|[A-Z]:\\Users\\|\.lody(?:/|\\)|/root/)' \
  docs/adr-010-transport-frame-boundary-for-zero-copy.md \
  docs/contents.md \
  docs/developers-guide.md \
  docs/execplans/10-1-3-approve-actor-and-codec-driver-boundary.md \
  docs/frame-vec-u8-inventory.md \
  docs/roadmap.md \
  docs/zero-copy-frame-and-payload-migration-roadmap.md || true

echo '== Planning-agent/session/operational metadata markers in ExecPlan =='
rg -n -i -C 3 \
  '(planning[ -]?agent|agent[ -]?(metadata|session)|session[ _-]?(id|metadata)|\.lody|workspace|transcript|prompt|model|run[ _-]?id|execution[ _-]?id)' \
  docs/execplans/10-1-3-approve-actor-and-codec-driver-boundary.md || true

echo '== ExecPlan references to local/repository paths =='
rg -n -C 2 '(?:^|[^[:alnum:]_])(docs|src|tests)/[[:alnum:]_./-]+' \
  docs/execplans/10-1-3-approve-actor-and-codec-driver-boundary.md || true

Length of output: 12649

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo '== Execution and retrospective sections =='
sed -n '430,620p' docs/execplans/10-1-3-approve-actor-and-codec-driver-boundary.md

echo '== Broad sensitive-token scan across the current PR diff =='
git diff --unified=0 "$(git merge-base HEAD origin/main)" HEAD -- docs |
  rg -n -i -C 2 \
  '(/home/|/Users/|[A-Z]:\\Users\\|\.lody|planning[ -]?agent|agent[ -]?session|session[ _-]?(id|metadata)|run[ _-]?id|execution[ _-]?id|api[_ -]?key|token|password|secret)' || true

Length of output: 9179

---

@leynos Not fully.

The absolute local-path exposure is resolved: the current PR documentation contains no /home/leynos/.lody/..., .lody, or other user-home path.

Remove the remaining planning/review-agent operational metadata from docs/execplans/10-1-3-approve-actor-and-codec-driver-boundary.md:

• Replace coderabbit review --agent with generic wording such as “run the automated review”.
• Replace the “Logisphere design review” heading and named reviewer personas (Telefono, Doggyllump, Buzzy Bee, Pandalump, Wafflecat) with an anonymized decision summary.
• Keep the substantive conditions and roadmap references, but attribute them generically—for example, “Design review identified the following conditions.”

Keep repository-relative paths and generic /tmp command-log examples; neither exposes a user-specific local path or session identifier.

[leynos]

@coderabbitai resume

[coderabbitai]

✅ Action performed

Reviews resumed.

[pandalump]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/execplans/10-1-3-approve-actor-and-codec-driver-boundary.md`:
- Around line 469-489: Narrow the ADR 010 validation in the ExecPlan’s assertion
and acceptance text: add a separate check that the ADR declares Status:
Accepted, and stop excluding the entire ADR file from the cross-reference scan.
Exclude only the documented preserved proposal-history lines while retaining
detection of future stale statuses or governing references within the ADR;
update the related acceptance criteria around the referenced section
consistently.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 428480bc-dda3-4818-b60e-53bee5ed5040

📥 Commits

Reviewing files that changed from the base of the PR and between 61a0f90 and 3b7b017.

📒 Files selected for processing (1)

• docs/execplans/10-1-3-approve-actor-and-codec-driver-boundary.md

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• leynos/rust-prover-tools (auto-detected)
• leynos/whitaker (auto-detected)
• leynos/shared-actions (auto-detected) → reviewed against open PR #295 10-1-3-approve-actor-and-codec-driver-boundary instead of the default branch

[leynos]

@coderabbitai Have the following now been resolved?

docs/execplans/10-1-3-approve-actor-and-codec-driver-boundary.md (1)

1-607: 📐 Maintainability & Code Quality | 🟠 Major | 🏗️ Heavy lift
Split the ExecPlan below the 400-line limit.
This 607-line Markdown file violates the repository limit. Move detailed research, historical execution notes, and supporting validation material into cohesive linked documents, leaving the ExecPlan as the concise execution record.

🤖 Detailed instructions

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @docs/execplans/10-1-3-approve-actor-and-codec-driver-boundary.md around
lines 1 - 607, The ExecPlan exceeds the repository’s 400-line limit. Split the
detailed research, historical execution notes, artefacts, and supporting
validation material from the main document into cohesive linked documentation,
while retaining the essential purpose, constraints, decisions, stages, concrete
steps, and acceptance criteria in the ExecPlan. Update cross-references so all
moved context remains discoverable, and ensure the resulting ExecPlan is under
400 lines without changing its documented scope or decisions.

Source: Coding guidelines

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

file='docs/execplans/10-1-3-approve-actor-and-codec-driver-boundary.md'

echo '== Exact line count =='
wc -l "$file"

echo '== Heading and link inventory =='
rg -n '^(#{1,6})\s|\[[^]]+\]\([^)]+\)' "$file" || true

echo '== Changed-file status and diff stat for the ExecPlan =='
git status --short -- "$file"
base="$(git merge-base HEAD origin/main)"
git diff --stat "$base" HEAD -- "$file"

Length of output: 2503

---

@leynos Not resolved.

docs/execplans/10-1-3-approve-actor-and-codec-driver-boundary.md is currently 634 lines, exceeding the 400-line limit by 234 lines.

Split the detailed historical/supporting material into linked documents, starting with:

• “Surprises & discoveries” (Lines 160–216)
• “Decision log” (Lines 217–290)
• “Outcomes & retrospective” (Lines 291–305)
• “Artefacts and notes”, including prior-art research and design-review conditions (Lines 549–590)

Retain the purpose, accepted decision, constraints, risks, progress, orientation, plan stages, concrete steps, validation, and recovery guidance in the ExecPlan. Link each extracted document from the relevant ExecPlan section and preserve the stated ADR 010 decision and roadmap scope.

[pandalump]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[leynos]

@coderabbitai stop asking for markdown documents to be split. The 400 line rule applies only to code.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@leynos Acknowledge the clarification. Apply the 400-line limit to code only; do not flag Markdown or other documentation files for exceeding it. Withdraw the ExecPlan splitting finding.

🐇

---

✏️ Learnings added

Learnt from: leynos
URL: https://github.com/leynos/wireframe/pull/540

Timestamp: 2026-07-21T08:49:03.655Z
Learning: In the leynos/wireframe repository, the 400-line file-length rule applies only to source code. Do not request splitting Markdown documentation or ExecPlan files solely because they exceed 400 lines.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

[codescene-access]

No quality gates enabled for this code.