feat(profiles): add session profile encoder and active-branch replay

[noxsystems]

Review size: this slice adds 236 changed lines (+212/-24) on top of #1918. GitHub's Files tab shows the cumulative diff with #1918 until it merges; review only commit 732a11f1b.

Summary

Part of #1064, slice 3b-i (persistence codec). Second and last pure PR of the codec: the encoder and the active-branch replay rule. Still no disk access, Pi API, Enter or routing change.

• Encoder: createSessionProfileBind(name, modelProfiles) creates only explicit user selections and rejects invalid input instead of manufacturing an empty snapshot; typed normalized routes may carry model/thinking as undefined and those are omitted, while effort stays strict. createSessionProfileClear() is the minimal {kind:"clear"}.
• Replay replaySessionProfileBranch(entries): the caller supplies entries already corroborated on disk, oldest to newest, on the active branch. The newest profile-family entry is terminal, including invalid and unsupported; an older binding is never revived. entryIndex is the actual branch offset for a later location warning. In-memory getBranch() alone is not corroboration; a subsequent disk-reader slice supplies it.
• Both directions return defensive snapshots.

This is PR 2 of 2.

Issue

Part of #1064

PR type

• New feature (type:feature)

Changes

Commit	Change
732a11f1b	Encoder, encoderInput mode in the route/snapshot readers, replaySessionProfileBranch, their tests, and the Replay section of docs/session-profile-format.md.

Test plan

Verified on top of PR 1, main 9782d26df, Node 25.2.1:

• tests/session-profile-persistence.test.ts: 18 pass, 0 fail (adds writer fields, undefined handling, defensive copies, terminal newest entry, branch order, sibling exclusion).
• tests/agent-profiles.test.ts + tests/model-routing-authority.test.ts: 59 pass, 0 fail.
• node scripts/check-types.mjs: 186 recorded diagnostics, no regressions.
• The same three files were independently verified byte-identical inside a bwrap sandbox against the pinned baseline (f5a42a5): 18/18, 59/59, ratchet 186 on both lanes.
• Native review (RDD): not run on this slice.

Chain Context

Field	Value
Chain	#1064 slice 3b-i: session profile persistence codec
Tracker PR	Not needed
Position	2 of 2
Base	main (fork PRs cannot stack bases; rebased as #1918 lands)
Depends on	#1918
Follow-up	#1922 disk corroboration, then Enter persistence wiring around #1824's selection path
Review budget	236 changed lines (+212/-24), of which 137 are tests and 29 docs.

main
 └─ #1918 decoder: record format, readSessionProfileEntry
   └─ PR 2 encoder + replaySessionProfileBranch                📍 this PR
     └─ #1922 readSessionProfileDisk: on-disk corroboration
       └─ (later) append controller, authority, Enter persistence wiring

Summary by CodeRabbit

• Documentation
  • Added guidance for the optional session profile format, including how profiles are bound or cleared, validated, and replayed across a session’s active history.
  • Clarified how invalid or unsupported profile entries affect replay and how model and route settings are represented.
• New Features
  • Added support for creating, reading, and replaying session profile entries, including preserving the selected entry’s position in session history.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: fb99714d-db4e-41a5-8fe2-782212c65959

📥 Commits

Reviewing files that changed from the base of the PR and between 9782d26 and 409ff09.

📒 Files selected for processing (3)

• docs/session-profile-format.md
• lib/session-profile-persistence.ts
• tests/session-profile-persistence.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

This change adds a v1 session-profile codec and active-branch replay utility. It validates bind payloads and route snapshots, classifies profile entries, and selects the newest non-absent result. Tests and documentation describe payload, validation, and replay behavior.

Changes

Session profile persistence

Layer / File(s)	Summary
Payload contracts and validation lib/session-profile-persistence.ts, tests/session-profile-persistence.test.ts	Adds payload and result types, validates profile bindings and routes, and creates bind and clear payloads. Tests cover payload creation, invalid input, and defensive copies.
Entry classification and branch replay lib/session-profile-persistence.ts, tests/session-profile-persistence.test.ts, docs/session-profile-format.md	Classifies entries as absent, bound, cleared, invalid, or unsupported. Replay returns the newest non-absent result and its branch index. Tests and documentation cover decoding and replay rules.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant replaySessionProfileBranch
  participant readSessionProfileEntry
  Caller->>replaySessionProfileBranch: Supply entries in oldest-to-newest branch order
  replaySessionProfileBranch->>readSessionProfileEntry: Classify each entry
  readSessionProfileEntry-->>replaySessionProfileBranch: Return entry status
  replaySessionProfileBranch-->>Caller: Return newest non-absent result and branch index

Loading

Merge Risk: ⚪ Minimal · up to 409ff

This adds a standalone session-profile codec and replay utility with tests and documentation. It is not yet wired into runtime behavior, so merge risk is minimal.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 10 functions across 2 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main changes: adding a session profile encoder and active-branch replay utility.

Full details: Docstring Coverage

Explanation

Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 10 functions across 2 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[barbatdev]

Approved. The encoder only emits explicit user selections, rejects invalid input instead of manufacturing an empty snapshot, strips undefined model and thinking, and keeps effort strict so the invalid-effort shape the decoder rejects can never be produced. The replay is terminal including invalid and unsupported, never revives an older binding, excludes sibling entries by the documented caller precondition, and both directions return defensive snapshots. The strict-effort divergence from #1918 stays consistent end to end.

Focused suites pass on my side (18/18 codec, 72/72 neighbors, typecheck at the 186-diagnostic baseline), plus an independent adversarial QA sweep: 23 probes over encoder hostility, replay orderings, revival attempts and defensive copies, all matching the contract.

One carried note from #1918 remains partially open: non-string customType and modelProfiles-level prototype isolation are still untested, and three more branches are only behaviorally covered. Fold them into #1922's suite, where the reader gives them a natural home. Replay input is structural, so #1922 should carry the corroboration enforcement at its own seam.