feat(feeds): serve signed catalog queries and changes

[giodl73-repo]

Summary

• expose signed changed-since pages and retention-reset responses
• persist revision-pinned query indexes for q, type, state, and publisherId
• expose signed bounded query pages with exact result counts
• issue short-lived integrity-protected cursors bound to feed, revision/range, normalized filters, page state, limits, and expiry
• use standard DSSE envelopes and fail closed when signing configuration is unavailable
• keep query materialization and response sizes bounded

Review unit

This PR combines the former signed change route (#3151) and indexed signed query route (#3160). Both are bounded projections over the distribution state from #3149 and use the shared ClawHub signer from #3005.

Sharded full snapshots remain separate in #3163.

Stack

Depends on #3149, #3005, and openclaw/rfcs#39.

Bounds

• change page: at most 500 records and 1 MiB
• query result page: at most 200 entries and 1 MiB
• query materialization batch: 250 entries
• continuation lifetime: five minutes
• query validity never exceeds the source revision expiry

Validation

• focused catalog publication, query, change-route, signing, rate-limit, and schema tests
• repository TypeScript and schema package build
• scoped type-aware oxlint and oxfmt
• git diff --check
• Codex review found no remaining actionable correctness regression

[vercel]

Someone is attempting to deploy a commit to the OpenClaw Foundation Team on Vercel.

A member of the Team first needs to authorize it.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed July 17, 2026, 11:33 PM ET / July 18, 2026, 03:33 UTC.

Summary
This draft adds revision-pinned catalog query materialization, signed DSSE query/change endpoints, retention-backed feed indexes, route rate limiting, schemas, tests, and hosted-feed specifications.

Reproducibility: not applicable. this is a feature PR, not a report of already-broken behavior. The supplied evidence does not include a real deployment run of the new query route.

Review metrics: 2 noteworthy metrics.

• Changed surface: 31 files; 4,827 added, 57 removed. The query feature carries schema, storage, transport, signing, retention, generated-package, test, and specification changes in one draft.
• Open prerequisites: 4 stacked PRs. The proposed endpoint depends on four unmerged feature layers, so it cannot yet be assessed as an independently landable change.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🦪 silver shellfish
Result: blocked until real behavior proof from a real setup is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Regenerate and commit the affected convex/_generated outputs, then rerun the repository’s Convex/type build gate.
• Resolve the raw-feed-to-DSSE compatibility decision with consumer owners and document the upgrade/rollback contract.
• Post redacted real deployment proof for query creation, DSSE verification, cursor continuation, and expired-materialization behavior.

Proof guidance:

• [P1] Needs real behavior proof before merge: The PR provides tests and static validation only; before merge it needs redacted real-deployment evidence of a signed query response, signature verification, cursor continuation, expiry behavior, and the intended compatibility cutover. After adding proof, update the PR body for a fresh review or ask a maintainer to comment @clawsweeper re-review.

Risk before merge

• [P1] Merging changes the existing /api/v1/feeds/plugins representation to DSSE and makes it fail with 503 when signer configuration is unavailable, which can break deployed raw-feed consumers before their trust configuration is upgraded.
• [P1] The branch introduces stored Convex schema/index state without the required committed generated artifacts, so repository builds and deployment type boundaries are not yet proven.
• [P1] The query endpoint is coupled to four still-open stack PRs, leaving its final API, signer rollout, and upgrade behavior difficult to validate independently.

Maintainer options:

1. Add a compatible signed-feed transition (recommended)
   Preserve the raw existing representation or use an explicit version/content-negotiation path, regenerate Convex artifacts, and prove both upgraded and pre-upgrade consumers before merge.
2. Accept coordinated cutover risk
   Approve DSSE-only delivery only after feed-consumer owners explicitly accept the raw-response break and operators confirm atomic signer provisioning and rollback steps.
3. Pause the stacked branch
   Keep this draft paused if maintainers do not want to commit to a public signed-feed contract and associated production trust root yet.

Next step before merge

• [P1] A maintainer must choose the public raw-feed/DSSE transition and signer rollout policy before a mechanical repair can make this stacked draft safe to merge.

Maintainer decision needed

• Question: Should the existing catalog-feed URL be converted in place to DSSE-only delivery, or should signed catalog delivery use an explicit compatibility/versioning transition until OpenClaw consumers and production signer provisioning are deployed?
• Rationale: This is a durable public feed and trust-boundary contract choice; the branch can implement either path, but source review cannot decide which upgrade break is acceptable.
• Likely owner: giodl73-repo — They authored the connected proposal chain and can provide the intended contract and deployment evidence; current-main ownership evidence was not available.
• Options:
  • Use an explicit transition (recommended): Keep the current raw response available and expose the signed representation through a versioned or negotiated path until consumer and production rollout proof exists.
  • Approve an in-place cutover: Accept the raw-feed compatibility break and required signer secret rollout as an intentional coordinated deployment with consumer owners.
  • Pause the stacked design: Defer the producer-side query/signing stack until maintainers settle the public catalog distribution contract.

Security
Cleared: The diff is security-sensitive because it introduces feed signing and private-key configuration, but the supplied patch evidence shows strict config parsing and no discrete credential leak or supply-chain execution path.

Review findings

• [P1] Preserve the existing raw catalog-feed contract — convex/http.ts:167-170
• [P1] Commit regenerated Convex API and data-model artifacts — convex/schema.ts:2664-2740

Review details

Best possible solution:

Land the feed protocol in reviewable slices: preserve or explicitly version the existing raw-feed contract until the matching consumer and signer provisioning are proven, regenerate committed Convex artifacts, then show a redacted real deployment transcript covering initial query, signed response verification, continuation cursor, expiry, and a pre-upgrade consumer path.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a feature PR, not a report of already-broken behavior. The supplied evidence does not include a real deployment run of the new query route.

Is this the best way to solve the issue?

No: converting the current catalog endpoint in place is not the safest established solution until consumer compatibility and signer provisioning are explicitly accepted; a compatible transition is narrower operationally.

Full review comments:

• [P1] Preserve the existing raw catalog-feed contract — convex/http.ts:167-170
  This replaces the established raw catalog document with a base64 DSSE envelope and a new media type, while the stacked consumer rollout remains outside this PR. Existing callers of this path will fail to parse the response or receive 503 before the signer secret is provisioned. Keep the raw form during a versioned/negotiated transition, or obtain explicit consumer-owner approval and upgrade proof for an intentional cutover.
  Confidence: 0.94
• [P1] Commit regenerated Convex API and data-model artifacts — convex/schema.ts:2664-2740
  This adds five Convex tables and several referenced internal functions, but no convex/_generated artifact is updated in the supplied diff. The repository commits these generated files for builds; regenerate and include them so the changed schema/function surface is actually type-checked and deployable from the branch.
  Confidence: 0.9

Overall correctness: patch is incorrect
Overall confidence: 0.9

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against aaa73625ed41.

Label changes

Label changes:

• add P2: This is a substantial catalog-distribution feature with bounded but non-urgent user impact; the main need is careful contract review before rollout.
• add merge-risk: 🚨 compatibility: Replacing the existing catalog-feed response with a DSSE envelope can break installed callers that parse the raw catalog document.
• add merge-risk: 🚨 security-boundary: The change introduces a production private-key signing configuration and a new consumer trust contract for public catalog data.
• add merge-risk: 🚨 availability: The changed established feed endpoint fails closed with 503 when signing configuration is missing or invalid.
• add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🦪 silver shellfish.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR provides tests and static validation only; before merge it needs redacted real-deployment evidence of a signed query response, signature verification, cursor continuation, expiry behavior, and the intended compatibility cutover. After adding proof, update the PR body for a fresh review or ask a maintainer to comment @clawsweeper re-review.

Label justifications:

• P2: This is a substantial catalog-distribution feature with bounded but non-urgent user impact; the main need is careful contract review before rollout.
• merge-risk: 🚨 compatibility: Replacing the existing catalog-feed response with a DSSE envelope can break installed callers that parse the raw catalog document.
• merge-risk: 🚨 security-boundary: The change introduces a production private-key signing configuration and a new consumer trust contract for public catalog data.
• merge-risk: 🚨 availability: The changed established feed endpoint fails closed with 503 when signing configuration is missing or invalid.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🦪 silver shellfish.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR provides tests and static validation only; before merge it needs redacted real-deployment evidence of a signed query response, signature verification, cursor continuation, expiry behavior, and the intended compatibility cutover. After adding proof, update the PR body for a fresh review or ask a maintainer to comment @clawsweeper re-review.

Evidence reviewed

What I checked:

• In-place catalog contract replacement: The route for the established catalog-feed path is changed from the existing raw feed handler to the signed DSSE handler, so current callers would receive an envelope instead of the previous catalog document. (convex/http.ts:167, e66b8ce4039c)
• Committed Convex artifacts are absent: The branch adds five schema tables and new internal functions but the supplied 31-file diff contains no update under convex/_generated, despite repository policy requiring generated Convex API/types to be committed for builds. (convex/schema.ts:2664, e66b8ce4039c)
• Unmerged stacked dependencies: The PR body states that it includes the still-open prerequisite work from feat: sign stored OpenClaw catalog publications #3005, feat(schema): add scalable catalog feed projections #3147, feat(feeds): add catalog distribution state #3149, and feat: serve signed catalog feed change pages #3151; the supplied related-item metadata confirms all remain open. (e66b8ce4039c)
• No real behavior proof: The PR body lists focused tests, type checks, linting, and review, but supplies no after-fix run against a real Convex deployment showing a signed query request, cursor continuation, and compatibility/rollout outcome. (e66b8ce4039c)
• Feature-chain provenance: The branch’s final feature commit follows the schema, journal, signer, and signed-change commits listed in the PR metadata, confirming this is a stacked producer-side delivery change rather than a narrow isolated query endpoint. (convex/httpApiV1/catalogFeedQuery.ts:1, e66b8ce4039c)

Likely related people:

• giodl73-repo: The available history identifies this person as author of the connected schema, durable-feed, signing, changes, query, and downstream sharding proposals; no current-main ownership trail was available in the supplied review evidence. (role: feature-chain author; confidence: low; commits: 029ad4e9c6fa, 5a4712106ec1, 04b12ce0e541; files: packages/schema/src/catalogFeedDistribution.ts, convex/catalogFeed.ts, convex/http.ts)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[clawsweeper]

ClawSweeper status: review started.

I am starting a fresh review of this pull request: feat(feeds): serve signed catalog queries and changes This is item 1/1 in the current shard. Shard 4/22.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.