Skip to content

Port Workflow trailing-delete reference from Marketing - #5

Merged
sweetmantech merged 3 commits into
mainfrom
claude/port-trailing-delete
Oct 25, 2026
Merged

sweetmantech merged 3 commits into
mainfrom
claude/port-trailing-delete

Conversation

@sweetmantech

@sweetmantech sweetmantech commented Oct 25, 2026 •

Copy link
Copy Markdown
Contributor

Row added to app#2352 after the final Mintlify comparison: docs.recoupable.dev (Mintlify, via docs#416) documents a newer DELETE /api/chats/{id}/messages/trailing contract 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.json and operation-inventory.json: shared fixtures, with the inventory pinned to api#1157 merge e217c79.
  • scripts/build_published_docs_record.py, scripts/build_response_contracts.py, new scripts/test_chat_trailing_contracts.py.
  • DOCUMENTATION-POLICY.md and an AGENTS.md contract note (Files account scope, trailing deletion).
  • manifest.json and llms-full.txt are regenerated by pnpm docs:build, not copied, so links stay on docs.recoupable.dev.

Marketing's content/STATUS.md is not ported: docs-site has no equivalent file.

Local checks

Check Result
refresh-contract-inventory.py --api <api@e217c79> --check 433 method/path pairs, 0 unmatched
build-contract-examples.py --api <api@e217c79> --check Verified shared examples
test_contract_inventory.py, test_response_contracts.py, test_chat_trailing_contracts.py pass
research.json vs Mintlify's /api-reference/openapi/research.json JSON-equal
pnpm test / type-check / lint / build 111 tests; clean; clean; 274 pages

Preview verification follows in a comment.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Documentation
    • Added API documentation for deleting a Workflow chat message and its inclusive chronological suffix, including authentication, ownership, and account override requirements.
    • Clarified conflict behavior when a workflow slot is occupied, concurrency limitations, and what success or transport failures do—and do not—guarantee.
    • Added documented response examples and error schemas for success and relevant failure statuses.

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>
@vercel

vercel Bot commented Oct 25, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
docs-site Ready Ready Preview Oct 25, 2026 10:14pm UTC

Request Review

@coderabbitai

coderabbitai Bot commented Oct 25, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

Warning

Review limit reached

You'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.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 538600ee-cdd5-4764-9769-dfc305c4ab0e
Commits

Reviewing files that changed from the base of the PR and between dc6ed52 and 262bbe8.

Files selected for processing: 10
  • AGENTS.md
  • DOCUMENTATION-POLICY.md
  • content/docs/contracts/example-cases.json
  • content/docs/contracts/operation-inventory.json
  • content/docs/manifest.json
  • content/docs/source/api-reference/openapi/research.json
  • content/docs/source/llms-full.txt
  • scripts/build_published_docs_record.py
  • scripts/build_response_contracts.py
  • scripts/test_chat_trailing_contracts.py

No actionable comments were generated in the recent review.

Recent review info
Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: ffd73a95-51ac-4d26-8bc9-4e113e4cc8a5
Commits

Reviewing files that changed from the base of the PR and between f83c4a6 and dc6ed52.

Files selected for processing: 10
  • AGENTS.md
  • DOCUMENTATION-POLICY.md
  • content/docs/contracts/example-cases.json
  • content/docs/contracts/operation-inventory.json
  • content/docs/manifest.json
  • content/docs/source/api-reference/openapi/research.json
  • content/docs/source/llms-full.txt
  • scripts/build_published_docs_record.py
  • scripts/build_response_contracts.py
  • scripts/test_chat_trailing_contracts.py

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Walkthrough

This PR updates documentation for guarded Files contracts and documents the trailing chat-message deletion API contract. It updates OpenAPI materials, examples, published contract records, export scripts, and contract tests for the trailing-delete operation.

Changes: Guarded Files guidance

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

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: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning 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 … Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed 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 te…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
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.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@sweetmantech

Copy link
Copy Markdown
Contributor Author

Preview verification on dc6ed52

Preview: docs-site-k8neqph0x-recoup.vercel.app (built from dc6ed52), compared against production Mintlify docs.recoupable.dev.

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 Trailing Chat Messages on the preview

"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.",

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

KISS

  • descriptions should be 4 sentences max. ideally 2-3.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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_at then id. Concurrent edit/resend is unsupported: stop other writers first, because an active workflow run returns 409. 200 means 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.

sweetmantech and others added 2 commits October 25, 2026 17:13
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>
@sweetmantech

Copy link
Copy Markdown
Contributor Author

Re-verified on 262bbe8 (review fix + main with #6 merged in)

Preview: docs-site-3b7kcwzsb-recoup.vercel.app (built from 262bbe8).

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.

@sweetmantech
sweetmantech merged commit 52ad8ae into main Oct 25, 2026
6 of 7 checks passed
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