feat(feeds): add catalog distribution state

[giodl73-repo]

## Feed stack (2 of 4 — ClawHub) **Review after:** #3005 (dormant signing foundation) **Then:** #3160 (paged query/delta transport) → #3163 (sharded snapshots) This branch is rebased directly on #3005. Its incremental range is `15b8dfba..ce757dc`; once #3005 lands, GitHub's `main` diff collapses to this PR's durable revision/history work. No production signing key is needed to review or merge this PR. Signing remains dormant until a later operator activation. ## Summary - define strict wire schemas for official catalog query, change, and reset projections - normalize bounded filters and validate identity, pagination, cursor, range, expiry, metadata, and featured-entry invariants - journal each official catalog publication as a durable revision with deterministic upsert, removal, and metadata records - persist exact per-revision and cumulative change counts - expose bounded indexed internal delta reads that return a retained range or `resetRequired` - retain history for 30 days and prune it in bounded scheduled batches - pin `generatedAt` across query/change page chains and cap every Convex page read ## Review unit This PR combines the former schema foundation (#3147) and durable history (#3149). The schemas and persisted revision model form one internal distribution-state contract. It adds no public route and performs no signing. ## Dependencies - #3005 — dormant signer and DSSE foundation - protocol contract: openclaw/rfcs#39 - next ClawHub slice: #3160 ## Boundaries No public HTTP endpoints, signing activation, cursor issuance, sharded snapshots, or OpenClaw consumer changes are included. ## Validation - focused schema and catalog tests: 48 passed - generated schema distribution package rebuilt - `git diff --check` - direct Codex incremental review against #3005: no actionable findings

[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 August 4, 2026, 11:25 PM ET / August 5, 2026, 03:25 UTC.

ClawSweeper review

What this changes

This PR adds catalog-feed query/change schemas plus retained Convex revision and delta state for later catalog distribution endpoints.

Merge readiness

⛔ Blocked until real behavior proof is added - 6 items remain

Keep open: current main still stores only one current catalog snapshot and lacks this PR’s revision journal and distribution schemas. The staged feature needs maintainer sponsorship, a current-base rebase, and real Convex behavior proof before merge; likely related people are Patrick Erichsen and Gio Della-Libera.

Priority: P2
Reviewed head: ce757dc325af83b1e6527e39feb0e9ef8dc824ba
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦪 silver shellfish (2/6)	The patch has focused coverage and green checks, but required after-fix runtime proof is absent.
Proof confidence	🦪 silver shellfish (2/6)	Needs real behavior proof before merge: Focused tests and CI are reported, but no redacted after-fix live Convex output proves publication, retained deltas or resets, and pruning; add it to the PR body for automatic re-review, or ask a maintainer to comment @clawsweeper re-review. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs real behavior proof before merge: Focused tests and CI are reported, but no redacted after-fix live Convex output proves publication, retained deltas or resets, and pruning; add it to the PR body for automatic re-review, or ask a maintainer to comment @clawsweeper re-review. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	6 items	Current main lacks the requested durable state: Current storePublication only replaces the one catalogFeedPublications row; it has no revision or change-journal write path. Current schema remains snapshot-only: Current main defines catalogFeedPublications but no catalogFeedRevisions or catalogFeedChanges tables. Feature is not released or on main: Neither a branch nor a tag contains the PR head, and current schema exports only the existing catalog-feed contract.
Findings	None	None.
Security	None	None.

How this fits together

ClawHub’s catalog publisher turns official package and skill records into stored feed snapshots. This PR adds a retained revision and change journal between publication and later query/delta transport, with scheduled cleanup of expired history.

flowchart LR
  A[Official packages and skills] --> B[Catalog publisher]
  B --> C[Current catalog snapshot]
  C --> D[Revision and change journal]
  D --> E[Bounded delta reader]
  D --> F[Retention scheduler]
  F --> G[Expired history removed]

Loading

Decision needed

Question	Recommendation
Should ClawHub adopt this retained catalog distribution-state foundation as the sponsored prerequisite for the later signed query, delta, and shard-feed stack?	Sponsor the staged foundation: Keep the architecture, require a current-base rebase and real runtime proof, then review the durable-state slice before downstream transport work.

Why: This is a large new data-model and protocol direction rather than a repair to an established behavior, and the downstream stack depends on the answer.

Before merge

• Add real behavior proof - Needs real behavior proof before merge: Focused tests and CI are reported, but no redacted after-fix live Convex output proves publication, retained deltas or resets, and pruning; add it to the PR body for automatic re-review, or ask a maintainer to comment @clawsweeper re-review. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Resolve merge risk (P1) - The branch is dirty against a newer main and includes an unmerged signing-foundation dependency, so its actual merge result is not yet demonstrated.
• Resolve merge risk (P1) - The new journal, retention cron, and downstream schema contract affect catalog freshness and reset behavior; mocked tests and CI do not prove them on a real Convex deployment.
• Resolve merge risk (P1) - The full branch adds an opt-in signed representation and secret-backed signer configuration, requiring explicit rollout and rollback confirmation alongside the existing unsigned client path.
• Complete next step (P2) - A maintainer must decide whether to sponsor this staged product direction; contributor runtime proof and a current-base rebase are then required before merge.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Full branch scope	23 files, +3,704/-25	The GitHub diff includes signing-foundation commits as well as the durable-state slice, making rebase review material.
Runtime/schema versus tests	runtime/schema/docs/generated +2,415/-23; tests +1,289/-2	The feature substantially expands persisted state and wire contracts while its validation remains primarily test-based.

Merge-risk options

Maintainer options:

1. Rebase and prove the staged contract (recommended)
   After maintainer sponsorship, rebase on current main and add redacted live Convex output covering publication, retained deltas, reset behavior, and bounded pruning.
2. Pause the feed stack
   Pause this PR if maintainers do not want to commit to the new retained-feed and signing direction before its transport consumers are ready.

Technical review

Best possible solution:

Adopt the retained distribution-state contract only if a maintainer sponsors the staged feed design, then rebase it on current main and provide redacted live Convex evidence for publication, deltas, reset, and pruning while preserving unsigned compatibility.

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

Not applicable: this is a new distribution capability, not a report of a broken existing behavior. Current main source confirms the requested retained revision and delta state does not exist.

Is this the best way to solve the issue?

Unclear: the staged separation is plausible, but it is not yet a maintainer-sponsored product direction and lacks live Convex evidence for its persistence and retention behavior.

AGENTS.md: found and applied where relevant.

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

Labels

Label justifications:

• P2: This is a substantial but currently inactive catalog-distribution feature, not an urgent regression.
• merge-risk: 🚨 compatibility: The branch adds exported feed-distribution contracts and content negotiation that downstream clients may depend on.
• merge-risk: 🚨 availability: Publication now writes retained journal state and depends on scheduled bounded cleanup for feed history.
• merge-risk: 🚨 security-boundary: The full stacked branch introduces opt-in DSSE responses and secret-backed signing configuration.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: Focused tests and CI are reported, but no redacted after-fix live Convex output proves publication, retained deltas or resets, and pruning; add it to the PR body for automatic re-review, or ask a maintainer to comment @clawsweeper re-review. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

What I checked:

• Current main lacks the requested durable state: Current storePublication only replaces the one catalogFeedPublications row; it has no revision or change-journal write path. (convex/catalogFeed.ts:487, 459caf625079)
• Current schema remains snapshot-only: Current main defines catalogFeedPublications but no catalogFeedRevisions or catalogFeedChanges tables. (convex/schema.ts:3021, 459caf625079)
• Feature is not released or on main: Neither a branch nor a tag contains the PR head, and current schema exports only the existing catalog-feed contract. (packages/schema/src/index.ts:5, 459caf625079)
• Stack boundary verified: The signing-foundation head 15b8dfba is an ancestor of this PR; the durable-state increment is 15 files and +2,374/-4 lines, while the GitHub PR remains a larger stacked diff. (convex/catalogFeed.ts:521, ce757dc325af)
• Current feed ownership trail: Blame and history place the current catalog publication/storage path and recent feed metadata work with Patrick Erichsen; the PR head’s durable-history commits are by Gio Della-Libera. (convex/catalogFeed.ts:474, b5890d3d9a4d)
• Required runtime proof is absent: The PR body reports tests and CI, but the supplied body and comments contain no redacted after-fix live Convex output showing publication, retained deltas/reset behavior, and pruning. (ce757dc325af)

Likely related people:

• Patrick Erichsen: Current snapshot storage and hosted-feed documentation are blamed to Patrick, and he authored the recent catalog metadata and featured-state work. (role: recent catalog-feed owner; confidence: high; commits: b5890d3d9a4d, 43e44a8eb6eb; files: convex/catalogFeed.ts, convex/schema.ts, specs/hosted-catalog-feed.md)
• Gio Della-Libera: Gio has a merged current-main catalog-feed contribution and authored the durable-state stack commits under review. (role: adjacent feed contributor; confidence: medium; commits: 5a3b050751f7, 82b0af791b07; files: convex/catalogFeed.ts, convex/schema.ts, packages/schema/src/catalogFeedDistribution.ts)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Add redacted live Convex output for publication, retained range reads, reset behavior, and pruning.
• Rebase after the signing-foundation dependency and current main are resolved.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
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.

Workflow

• 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.

History

Review history (3 earlier review cycles)

• reviewed 2026-07-21T16:56:32.203Z sha 1df84c4 :: needs real behavior proof before merge. :: none
• reviewed 2026-07-22T05:33:29.015Z sha 1df84c4 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-05T02:09:04.011Z sha ce757dc :: needs real behavior proof before merge. :: none

[github-actions]

This pull request has been automatically marked as stale due to inactivity.
Please update it or it will be closed.

[github-actions]

This pull request has been automatically marked as stale due to inactivity.
Please update it or it will be closed.