docs: trajectory→convergence integration contract#34
Conversation
Document how the trajectory (reasoning) lens maps into the Agent Relay Loop convergence store: the envelope, field mapping, deterministic kind-namespaced event-id scheme, server-owned transforms (confidence→basis points, Task enrichment, scrub), v1 distilled scope vs deferred chapter stream, and the shared traj_abc acceptance fixture. Source-side companion to the WS-1 ADR. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
Warning Review limit reached
More reviews will be available in 17 minutes and 43 seconds. Learn how PR review limits work. Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file). ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits. 🚦 How do rate limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughAdds ChangesConvergence Integration Contract Documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a new documentation file, docs/convergence-integration.md, which defines the integration contract and field mappings for the trajectory reasoning lens within the Agent Relay Loop convergence store. The review feedback highlights two necessary corrections in the documentation tables: updating the schema path for status to reflect its correct location under Trajectory rather than Trajectory.task, and prefixing decisions[i] with retrospective in the event-id scheme table to maintain consistency with other retrospective-related rows.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| | `TrajectoryEvent.raw` | — | **dropped** by default-tier scrub; never emitted | | ||
| | `agents[].name` / `chapter.agentName` (`persona_id`) | `actorName` | "which engineer/agent" attribution | | ||
| | `Trajectory.projectId` | `projectId` | | | ||
| | `Trajectory.task.title/description/status` | `taskTitle` / `taskDescription` / `taskStatus` | structured fields; `taskTitle` feeds embedding via server `Task:` enrichment | |
There was a problem hiding this comment.
In src/core/schema.ts, status is a direct property of Trajectory (Trajectory.status), not nested under Trajectory.task (Trajectory.task.status). The table should be updated to reflect this correct path.
| | `Trajectory.task.title/description/status` | `taskTitle` / `taskDescription` / `taskStatus` | structured fields; `taskTitle` feeds embedding via server `Task:` enrichment | | |
| | Trajectory.task.title/description and Trajectory.status | taskTitle / taskDescription / taskStatus | structured fields; taskTitle feeds embedding via server Task: enrichment | |
| | Source | `kind` | `eventId` | | ||
| | --- | --- | --- | | ||
| | chapter stream event | (event type) | `trajevent:<chapterId>:<arrayIndex>` *(deferred — see scope)* | | ||
| | decision[i] | `decision` | `decision:<trajectoryId>:<i>` | |
There was a problem hiding this comment.
To align with the other retrospective fields in this table (such as retrospective learnings[i], retrospective challenges[i], etc.), this row should be prefixed with retrospective and refer to decisions[i] since decisions is nested under the retrospective object in the schema.
| | decision[i] | `decision` | `decision:<trajectoryId>:<i>` | | |
| | retrospective decisions[i] | decision | decision:<trajectoryId>:<i> | |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (4)
docs/convergence-integration.md (4)
64-66: ⚡ Quick winClarify whether
taskRefis always emitted or omitted when null.Line 66 describes
Trajectory.task.source {system,id}→taskRefas "future cross-lens correlation seed (oftennull; not persisted byai-histyet)". It is unclear whether:
taskRefis always present in the envelope (even when null), ortaskRefis omitted from the envelope when null (i.e., optional field).Clarify the presence/absence rule (e.g., "Always emit
taskRefif present, omit if null" or "Always emit with null if not available").🤖 Prompt for 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. In `@docs/convergence-integration.md` around lines 64 - 66, The `taskRef` field description in the Trajectory mapping table lacks clarity about whether it is always emitted in the envelope or omitted when null. Update the description for the `Trajectory.task.source {system,id}` → `taskRef` mapping row to explicitly state the presence/absence rule, such as "Always emit taskRef if present, omit if null" or "Always emit with null if not available", so readers understand whether taskRef is an optional field in the envelope or always included regardless of value.
51-70: ⚡ Quick winClarify Retrospective fan-out field mapping.
Line 68 references "fan-out events — see below" for
Retrospective.{summary,approach,learnings[],suggestions[],challenges[]}, but the actual event-id mapping is in the event-id scheme table (lines 78–86), not immediately below. To avoid reader confusion, make the Retrospective-to-eventId mapping explicit in the field mapping table or add a direct cross-reference to the event-id scheme section.For implementer clarity, state which Retrospective fields produce which event kinds (e.g.,
summaryandapproach→reflection,learnings→finding:…:learning,suggestions→reflection:…:suggestion,challenges→finding:…:challenge).🤖 Prompt for 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. In `@docs/convergence-integration.md` around lines 51 - 70, The Retrospective row in the field mapping table references fan-out events with "see below" but the actual event-id mapping is located in a separate table section (event-id scheme), causing confusion about which specific Retrospective fields map to which event types. Update the Retrospective row in the field mapping table to explicitly state the mapping between each Retrospective field and its corresponding event kind (for example: summary and approach fields map to reflection events, learnings array maps to finding:learning events, suggestions array maps to reflection:suggestion events, and challenges array maps to finding:challenge events), or add a direct cross-reference that clearly directs readers to the event-id scheme section where the complete mapping is defined.
127-150: ⚡ Quick winExplicitly document confidence inheritance for nested retrospective arrays.
The acceptance fixture shows that
learning:0,suggestion:0, andchallenge:0haveconfidence_basis_points = null, implying they inherit confidence from their parent retrospective event. This is correct, but it is not stated explicitly in the prose. Add a note to the fixture description (or to the field mapping table at line 60) to clarify that nested retrospective array elements (learnings, suggestions, challenges) do not carry their own confidence and instead inherit from the parentRetrospective.confidence(if present).This avoids implementer confusion: "Should my Learning event have its own confidence or null?"
🤖 Prompt for 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. In `@docs/convergence-integration.md` around lines 127 - 150, The acceptance fixture table for traj_abc shows that nested retrospective array elements (learning:0, suggestion:0, challenge:0) have null confidence_basis_points values, but this inheritance behavior from the parent Retrospective.confidence is not explicitly documented in the prose description. Add a clarifying note in the fixture description section that explicitly states nested retrospective array elements do not carry their own confidence values and instead inherit confidence from their parent Retrospective event. This note should be added either immediately after the fixture table or referenced in relation to the field mapping table to prevent implementer confusion about whether Learning, Suggestion, and Challenge events should have their own confidence values.
22-48: 💤 Low valueAdd note that envelope example is abbreviated.
The convergence envelope JSON example (lines 28–44) is representative but omits fields listed in the field mapping table, such as
significance,tags,projectId,taskDescription,taskStatus,taskRef,filesTouched, andcodeChurn.Add a brief note (e.g., "Example shows commonly-emitted fields; see the field mapping table for the full set.") to signal that the example is not exhaustive. This prevents implementers from assuming omitted fields should never be sent.
🤖 Prompt for 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. In `@docs/convergence-integration.md` around lines 22 - 48, The convergence envelope JSON example in the documentation is incomplete and lacks any indication that it is abbreviated. Add a clarifying note immediately after the code example closing backtick that states the example shows commonly-emitted fields and directs implementers to refer to the field mapping table for the complete set of supported fields, explicitly mentioning that omitted fields like significance, tags, projectId, taskDescription, taskStatus, taskRef, filesTouched, and codeChurn can and should be sent as needed.
🤖 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.
Nitpick comments:
In `@docs/convergence-integration.md`:
- Around line 64-66: The `taskRef` field description in the Trajectory mapping
table lacks clarity about whether it is always emitted in the envelope or
omitted when null. Update the description for the `Trajectory.task.source
{system,id}` → `taskRef` mapping row to explicitly state the presence/absence
rule, such as "Always emit taskRef if present, omit if null" or "Always emit
with null if not available", so readers understand whether taskRef is an
optional field in the envelope or always included regardless of value.
- Around line 51-70: The Retrospective row in the field mapping table references
fan-out events with "see below" but the actual event-id mapping is located in a
separate table section (event-id scheme), causing confusion about which specific
Retrospective fields map to which event types. Update the Retrospective row in
the field mapping table to explicitly state the mapping between each
Retrospective field and its corresponding event kind (for example: summary and
approach fields map to reflection events, learnings array maps to
finding:learning events, suggestions array maps to reflection:suggestion events,
and challenges array maps to finding:challenge events), or add a direct
cross-reference that clearly directs readers to the event-id scheme section
where the complete mapping is defined.
- Around line 127-150: The acceptance fixture table for traj_abc shows that
nested retrospective array elements (learning:0, suggestion:0, challenge:0) have
null confidence_basis_points values, but this inheritance behavior from the
parent Retrospective.confidence is not explicitly documented in the prose
description. Add a clarifying note in the fixture description section that
explicitly states nested retrospective array elements do not carry their own
confidence values and instead inherit confidence from their parent Retrospective
event. This note should be added either immediately after the fixture table or
referenced in relation to the field mapping table to prevent implementer
confusion about whether Learning, Suggestion, and Challenge events should have
their own confidence values.
- Around line 22-48: The convergence envelope JSON example in the documentation
is incomplete and lacks any indication that it is abbreviated. Add a clarifying
note immediately after the code example closing backtick that states the example
shows commonly-emitted fields and directs implementers to refer to the field
mapping table for the complete set of supported fields, explicitly mentioning
that omitted fields like significance, tags, projectId, taskDescription,
taskStatus, taskRef, filesTouched, and codeChurn can and should be sent as
needed.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 41e9079f-dd04-45df-bbee-cb1bd1fd54c3
📒 Files selected for processing (1)
docs/convergence-integration.md
…enda v1.1 = the compacted roll-up → convergence-event contract PR #26 implemented against. v1.2 = the Learn lens spec (distill session history into Pair signal for users without trajectories): input adapter, learn_<hash> idempotent eventIds, client-side LLM-locality privacy gate, summary-downweight ranking note, learn_fixture acceptance + scrub-bait. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
All CI-equivalent steps pass for the actual tracked tree:
I made no edits. The PR is a pure, additive documentation file whose factual claims I verified against the repo's actual code. Review SummaryPR #34 adds one new file: Verification of doc claims against this repo's code:
CI impact: None. Fixes applied: None needed. Biome ignores markdown, and there's no markdownlint/spell tooling, so no mechanical changes apply. Addressed comments
Advisory Notes
This PR is a clean documentation addition with no code risk and accurate technical claims. It does not require my judgment to gate a human — but since there were no outstanding comments, no CI failures attributable to the change, and no merge-conflict signal available in the provided context, I leave the merge decision to the maintainer. |
1 participant
Adds `docs/convergence-integration.md` — the agent-facing reference for how the trajectory (reasoning) lens maps into the Agent Relay Loop convergence store. Source-side companion to the WS-1 ADR in `relayhistory-cloud` (which remains authoritative).
What it documents
POST /v1/ingestrecords), tenancy server-derived.trajectories/src/core/schema.ts→ convergence fields.decision:<traj>:<i>,finding:<traj>:learning:<i>,reflection:<traj>:suggestion:<i>, etc.) and the rules that keep it collision-free.Task:content enrichment, scrub/raw-drop.traj_abcacceptance fixture (6 rows), pinned by both the Rust client test and the relayhistory-cloud PGlite server test.Context
Output of the WS-1 convergence work this session. Documents the ratified contract from the trajectory source side so trajectory-tool authors find it in this repo. Docs-only; no code changes.
🤖 Generated with Claude Code