Skip to content

docs(agents): record the riptide-emission and cost invariants - #187

Merged
trick77 merged 1 commit into
masterfrom
agents-md-invariants
Sep 8, 2026
Merged

trick77 merged 1 commit into
masterfrom
agents-md-invariants

Conversation

@trick77

@trick77 trick77 commented Sep 8, 2026

Copy link
Copy Markdown
Owner

The file was already terse and rule-shaped — nothing to compress. What it lacked were invariants, several of which cost real debugging to establish:

  • Emission is best-effort. A slow, rejecting or absent riptide must never fail a webhook or block a review.
  • The rollup is claimed before the POST. riptide_emitted_at is stamped by the statement that reads the snapshot, so a rejected emission is never retried — which means a payload riptide's strict schema rejects 422s every rollup, not just the one carrying a new field. Hence: deploy the riptide side first when adding a field. This is exactly what would have bitten us on fix(riptide): report the reviewer account, stop dropping unpriced rollups #186.
  • Unknown cost → omit it. Never 0 (understates spend), never drop the rollup (outcome, diff size, tokens and runs need no price). This was the bug fixed in fix(riptide): report the reviewer account, stop dropping unpriced rollups #186: an unpriced model silently withheld whole PR records.
  • Declare our own identity. riptide keeps no bot names of its own; undeclared, our comments count as a human's and its review-pickup metric collapses to seconds.
  • A None cost fails open — an unpriced model must never block a review; the per-PR cap skips only subsequent auto-runs.
  • The disagree mechanic was removed deliberately in migration 009, noted so nobody reinstates it from older docs.

1 331 → 3 151 chars, still well inside budget. Docs only; 649 tests pass.

Candidates I did not add, because they need a proper read of the review path rather than a passing look: the deadline-exceeded summary rules, the "never post an empty summary" rule, and the network-error-does-not-mark-ignored rule. Worth a follow-up pass.

Style was already terse; what was missing were invariants the code enforces
and that cost real debugging to find: emission is best-effort, the rollup is
claimed before the POST so a rejected one is never retried (hence deploy
riptide first when adding a field), an unknown cost is omitted rather than
zeroed or dropped, we declare our own account, and a None cost fails open.

Also notes that the disagree mechanic was removed deliberately in 009, so it
does not get reintroduced by someone reading the older docs.
@trick77
trick77 merged commit ef8d39d into master Sep 8, 2026
2 checks passed
@trick77
trick77 deleted the agents-md-invariants branch September 8, 2026 14:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant