Skip to content

docs(predict): correct the C1 contract against what shipped - #38341

Merged
matallui merged 1 commit into
mainfrom
fix/pred-1402-contract-corrections
Oct 28, 2026
Merged

matallui merged 1 commit into
mainfrom
fix/pred-1402-contract-corrections

Conversation

@matallui

@matallui matallui commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

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):

  1. Settlement entries are the net held side, not per side. yes_count_fp and no_count_fp are 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_result names the winning side, which is often not the held one.
  2. fee_cost is never subtracted from settlement realizedPnl. It is the market's trading fees, already inside the cost basis. The document subtracted it twice; the shipped C4 code does not.
  3. settlementsCompleteFrom added. 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.
  4. The Activity tie order is pinned: timestamp descending, then kind (trade before settlement), then id ascending. "then entry kind, then id" was not a total order.
  5. averagePrice and costBasis are optional when the backend's Order ledger cannot account for the holding — the same rule the document already had for realizedPnl. With them absent, PnL is absent and the Summary reports complete: false.
  6. openedAt is 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 in test/fixtures/kalshi-demo-activity.json.

Screenshots/Recordings

N/A — documentation only.

Pre-merge author checklist

Performance checks (if applicable)

  • I've tested on Android
    • Not applicable: documentation-only change, no app behaviour to test.
  • I've tested with a power user scenario
    • Not applicable for the same reason.
  • I've instrumented key operations with Sentry traces for production performance metrics
    • Not applicable for the same reason.

Pre-merge reviewer checklist

  • I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
  • I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.

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.
@github-actions

Copy link
Copy Markdown
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.

@metamask-ci metamask-ci Bot added team-predict Predict team INVALID-PR-TEMPLATE PR's body doesn't match template labels Oct 27, 2026
@matallui matallui removed the INVALID-PR-TEMPLATE PR's body doesn't match template label Oct 27, 2026
@matallui
matallui marked this pull request as ready for review October 27, 2026 23:09
@matallui
matallui requested a review from a team as a code owner October 27, 2026 23:09
@matallui
matallui enabled auto-merge October 27, 2026 23:10
@matallui matallui added the no-changelog no-changelog Indicates no external facing user changes, therefore no changelog documentation needed label Oct 27, 2026
@sonarqubecloud

Copy link
Copy Markdown

@matallui
matallui added this pull request to the merge queue Oct 28, 2026
Merged via the queue into main with commit 2535841 Oct 28, 2026
142 checks passed
@matallui
matallui deleted the fix/pred-1402-contract-corrections branch October 28, 2026 12:37
@github-actions github-actions Bot locked and limited conversation to collaborators Oct 28, 2026
@metamask-ci metamask-ci Bot added the release-8.19.0 Issue or pull request that will be included in release 8.19.0 label Oct 28, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

no-changelog no-changelog Indicates no external facing user changes, therefore no changelog documentation needed release-8.19.0 Issue or pull request that will be included in release 8.19.0 size-XS team-predict Predict team

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants