Repository navigation
docs(predict): correct the C1 contract against what shipped - #38341
Merged
Merged
Conversation
The settlement entries were described per side with holdings semantics; Kalshi reports lifetime acquisitions, so the held side is the difference. Also: no fee_cost double subtraction, settlementsCompleteFrom, the trade-before-settlement tie order, optional averagePrice/costBasis, and openedAt as a sorting sentinel rather than a persisted observation.
Contributor
|
CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes. |
matallui
marked this pull request as ready for review
October 27, 2026 23:09
matallui
enabled auto-merge
October 27, 2026 23:10
|
caieu
approved these changes
Oct 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.



Description
The C1 canonical portfolio/Activity contract (
app/components/UI/PredictNext/docs/canonical-portfolio-activity-catalog-contract.md) still described the model we assumed before C4 and C3 were built against Kalshi's real payloads. This PR corrects the document; no app code changes.Eight corrections, each found while building PRED-1380 (C4) and PRED-1378 (C3):
yes_count_fpandno_count_fpare lifetime acquisitions, not holdings — a sale of YES is booked as an acquisition of NO — so a Market settles|yes − no|contracts on the side the counts favour, and equal counts mean a flat Position with no entry. The previous wording described holdings, and read literally it pays out on a flat market.market_resultnames the winning side, which is often not the held one.fee_costis never subtracted from settlementrealizedPnl. It is the market's trading fees, already inside the cost basis. The document subtracted it twice; the shipped C4 code does not.settlementsCompleteFromadded. Kalshi archives settled positions and stops serving their records, so a page that can reach the archive horizon says from when Settlements are complete, while Trades stay complete throughout.timestampdescending, then kind (tradebeforesettlement), thenidascending. "then entry kind, then id" was not a total order.averagePriceandcostBasisare optional when the backend's Order ledger cannot account for the holding — the same rule the document already had forrealizedPnl. With them absent, PnL is absent and the Summary reportscomplete: false.openedAtis a sorting sentinel, not a persisted first-observed time, when the ledger cannot establish the holding.Why it matters now: C5 (PRED-1404) will write the mobile parser against these rules, so landing this first keeps it from encoding rules we already know are wrong.
Scope note: this is a documentation change only. The performance checks in the author checklist were assessed and are not applicable — nothing here runs on a device.
Changelog
CHANGELOG entry: null
Related issues
Refs: PRED-1402 (C1 contract), PRED-1378 (C3), PRED-1380 (C4), PRED-1404 (C5)
Manual testing steps
N/A — documentation only, no app code touched. Verified by reading the changed file against the merged C4 derivation (
apps/api/src/app/portfolio/kalshi-activity.mappers.ts), the C3 implementation in predict-api #63, and the recorded Kalshi demo payloads intest/fixtures/kalshi-demo-activity.json.Screenshots/Recordings
N/A — documentation only.
Pre-merge author checklist
Performance checks (if applicable)
Pre-merge reviewer checklist