Repository navigation
Port Workflow trailing-delete reference from Marketing - #5
Conversation
Brings over Marketing c3fc77f, 4d06a2d and d4111d3, written after the
docs-site port point (Marketing 40bc362): the bounded
DELETE /api/chats/{id}/messages/trailing reference, its shared fixtures and
producer test, the Files contributor note, and the inventory pin to the
merged api #1157 (e217c79). manifest.json and llms-full.txt are regenerated
with pnpm docs:build rather than copied.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Warning Review limit reachedYou've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. Next included review available in 26 minutes. View limit details
No actionable comments were generated in the recent review.
|
| Layer / File(s) | Summary |
|---|---|
Guarded Files contract guidance AGENTS.md, DOCUMENTATION-POLICY.md |
The guidance describes Files read contracts, account-scoped behavior, test coverage, release and revision-pinning steps, and the limits of mocked checks. |
Trailing chat-message deletion contract
| Layer / File(s) | Summary |
|---|---|
Trailing-delete API contract content/docs/source/api-reference/openapi/research.json, content/docs/source/llms-full.txt, content/docs/contracts/example-cases.json, DOCUMENTATION-POLICY.md |
The API contract and examples document the owned Workflow chat, inclusive timestamp-and-UUID deletion boundary, authentication options, response conditions, and concurrency limitations. |
Published contract records and checks scripts/build_published_docs_record.py, scripts/build_response_contracts.py, scripts/test_chat_trailing_contracts.py, content/docs/contracts/operation-inventory.json |
The export scripts include the trailing-delete operation and response examples. Tests check exported contract details, and the inventory records the updated source revision and specification hash. |
Priority:
Estimated code review effort: 3 (Moderate) | ~20 minutes
Change: Other
Possibly related issues
recoupable/app#2352— The issue concerns moving API documentation to a standalone docs site; this PR updates API contract materials in the docs site.recoupable/mono#360— The issue concerns detecting contract drift; this PR updates the operation inventory and adds producer and contract tests.recoupable/mono#320— The issue concerns discoverable API operations and authentication guidance; this PR documents the trailing-delete operation, authentication, examples, and response contracts.
Possibly related PRs
- recoupable/docs-site#2 — The MCP server reads API pages and referenced schemas from the docs site, including the operation and authentication schema updated here.
Merge Risk: 
Minimal · up to dc6ed
-
No actionable issue remains in the reviewed documentation and contract changes; they are mergeable after normal checks.
Pre-merge checks: 
4 · 
1
-
Failed checks: 1 warning Passed checks: 4 passed-
Full details: Title check
-
Explanation
The title names the Marketing source and the Workflow trailing-delete reference. The changeset ports the bounded DELETE /api/chats/{id}/messages/trailing contract, its shared fixtures, scripts, and tests into the docs site. The title covers the main change, but it does not say the change is a port to the docs site. It also uses the word 'Port' as a term that a teammate may not parse, and it omits that the change adds a new endpoint contract.
-
Full details: Docstring Coverage
-
Explanation
Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 3 files. (6 skipped: 6 unsupported.)
Resolution
Write docstrings for the functions missing them to satisfy the coverage threshold.
-
Finishing Touches: 💡 1
-
📝 Generate docstrings: 💡
-
- Commit to this branch
- Create a new PR
🧪 Generate unit tests (beta)
-
- Commit to this branch
- Create a new PR
-
- Autofix · 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.
Comment @coderabbitai help to get the list of available commands.
Preview verification on
|
| Check | Result |
|---|---|
All 13 specs: /spec/<name>.json vs Mintlify /api-reference/openapi/<name>.json |
JSON-equal, 13/13 (before this PR: research.json differed on the trailing-delete operation) |
llms-full.txt vs Mintlify, with Mintlify's recoupable.dev/docs links mapped to docs.recoupable.dev |
0 differing lines (before: 129) |
/api-reference/chat/messages-trailing-delete HTML |
new description, account_id query parameter, 409 response, DeleteTrailingChatAuthenticationErrorResponse all rendered |
.md for the same page |
## DELETE /api/chats/{id}/messages/trailing with the new operation and the 409 response |
| Crawl: 230 nav pages + agent URLs | 233 × 200, plus GET /mcp → 405 (POST-only, expected) |
Contract checks against api e217c79 (the inventory pin) pass: 433 method/path pairs, 0 unmatched; shared examples verified.
| "delete": { | ||
| "operationId": "deleteChatsByIdMessagesTrailing", | ||
| "description": "Delete all messages in a chat from a given message onward (inclusive), identified by `from_message_id`.", | ||
| "description": "Delete one persisted Workflow chat message and its inclusive suffix, ordered by `created_at` then `id`. The anchor must belong to the owned Workflow chat; legacy chat memories are not read or deleted. Authenticate with exactly one of `x-api-key` or `Authorization: Bearer`. Ownership is checked against the chat session's effective account, including an authorized `account_id` query override.\n\nThe caller must ensure there are no concurrent or outstanding message writers, including queued persistence and other edits. Any observed nonnull workflow slot returns `409` without cancelling work or clearing the slot. A null slot or a successful Stop does not prove that outstanding writers have finished. Concurrent edit/resend is unsupported.\n\nThe delete is scoped to this chat and includes the anchor, messages with a later timestamp, and messages at the same timestamp whose UUID sorts at or after the anchor UUID. Earlier UUIDs at the same timestamp survive; timestamp precision is preserved.\n\n`200` means the delete statement succeeded, possibly affecting zero rows. It does not report a deleted-row count or guarantee durable absence or prevent later message recreation. A transport failure can leave the commit outcome unknown: refresh authoritative history before deciding what to do next, rather than blindly resending a turn.", |
There was a problem hiding this comment.
KISS
- descriptions should be 4 sentences max. ideally 2-3.
There was a problem hiding this comment.
Fixed in 262bbe8 (with main merged in). The description was 13 sentences; it is now three:
Delete a message in a Workflow chat and every message after it, ordered by
created_atthenid. Concurrent edit/resend is unsupported: stop other writers first, because an active workflow run returns409.200means the delete ran, possibly affecting zero rows; after a transport failure, refresh the chat history instead of resending.
The parameters, security and per-status responses still carry the detail that was cut. scripts/test_chat_trailing_contracts.py now fails if the description exceeds three sentences (RED at 13, GREEN at 3).
The API keeps a copy of this text in lib/contracts/fixtures/published-docs.json, which docs CI compares at the pinned API commit, so the matching fixture is in api#1160. Merge order: api#1160, then I re-pin operation-inventory.json here to its merge commit, then this PR. Until then the documentation-contract check fails against e217c79, as expected.
Review on #5: operation descriptions stay at 2-3 sentences (4 max). The 13-sentence description becomes three; parameters, security and per-status responses keep the detail. The producer test now enforces the limit. Regenerated example-cases.json, the research.json inventory hash, manifest and llms-full.txt. The matching API fixture is api#1160; the inventory re-pins to its merge commit once it lands. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Re-verified on
|
| Check | Result |
|---|---|
| Trailing-delete page HTML | new 3-sentence description rendered; old text ("Delete one persisted Workflow chat message") gone; 409 response and parameter descriptions intact |
/spec/research.json |
serves the new description |
| Crawl: 230 nav pages + agent URLs | 233 × 200, plus GET /mcp → 405 (same as Mintlify) |
#6 routes after the merge (/sitemap.xml, /robots.txt, /skill.md) |
200 |
CI test, build, cli-guide |
pass |
CI check |
fails as expected: Stale documentation example fixture at the pinned API e217c79. api#1160 carries the matching fixture; locally build-contract-examples.py --check passes against its head |
Next: after api#1160 merges, re-pin operation-inventory.json to its merge commit; check should then pass. research.json now intentionally differs from Mintlify's copy on this one description.

Row added to app#2352 after the final Mintlify comparison:
docs.recoupable.dev(Mintlify, via docs#416) documents a newerDELETE /api/chats/{id}/messages/trailingcontract than this site. The source change landed in Marketing after the docs-site port point (40bc362).What this ports
Marketing
40bc362..d4111d3(c3fc77f,4d06a2d, merged via marketing#241;d4111d3, marketing#231):research.json: the bounded Workflow trailing-delete operation (security,account_id, 400/401/403/404/409/500 descriptions, 200 examples,DeleteTrailingChatAuthenticationErrorResponse).content/docs/contracts/example-cases.jsonandoperation-inventory.json: shared fixtures, with the inventory pinned to api#1157 mergee217c79.scripts/build_published_docs_record.py,scripts/build_response_contracts.py, newscripts/test_chat_trailing_contracts.py.DOCUMENTATION-POLICY.mdand anAGENTS.mdcontract note (Files account scope, trailing deletion).manifest.jsonandllms-full.txtare regenerated bypnpm docs:build, not copied, so links stay ondocs.recoupable.dev.Marketing's
content/STATUS.mdis not ported: docs-site has no equivalent file.Local checks
refresh-contract-inventory.py --api <api@e217c79> --checkbuild-contract-examples.py --api <api@e217c79> --checktest_contract_inventory.py,test_response_contracts.py,test_chat_trailing_contracts.pyresearch.jsonvs Mintlify's/api-reference/openapi/research.jsonpnpm test/type-check/lint/buildPreview verification follows in a comment.
🤖 Generated with Claude Code
Summary by CodeRabbit