feat(feeds): publish sharded catalog snapshots

[giodl73-repo]

## Feed stack (4 of 4 — ClawHub) **Review after:** #3005 → #3149 → #3160 **Consumer:** openclaw/openclaw#110250, after openclaw/openclaw#101981 This branch is rebased directly on #3160. Its incremental range is `428b4fa2..dec1587`; after the predecessors land, the PR diff collapses to sharded snapshot publication and delivery only. No production signing key is needed to review or merge this PR. Production signing remains a later operator activation. ## Summary Completes the ClawHub producer side of hosted catalog distribution with signed shard roots and immutable digest-addressed plugin/skill shards. ## What changes - defines strict shard-root, descriptor, and shard schemas with exact-byte SHA-256 verification and bounded aggregate limits - applies the same entry metadata invariants to atomic and sharded feeds - publishes complete plugin and skill snapshots as immutable shards before atomically making the root and current query projection visible - stores lightweight descriptors separately so root reads do not load shard payload bytes - retains immutable shards through at least their advertised `expiresAt` - serializes publication actions with a recoverable lease and queues overlapping workflow runs - exposes public `/v1/feeds/**` URLs through the existing Nitro-to-Convex `/api/v1/feeds/**` proxy - fetches plugin and skill families through bounded internal pages, with an explicit service-runtime ceiling that prevents Convex action exhaustion ## Bounds - current ClawHub publication runtime: at most 10,000 entries and 8 MiB of collected entry bytes per feed

• wire shard: at most 1 MiB and 10,000 entries - ClawHub stored shard target: at most 900 KiB to reserve Convex document overhead - root: at most 1 MiB, 1,024 shards, and 1,000,000 entries - aggregate described shard bytes: at most 256 MiB; the 1,000,000-entry root limit is protocol headroom for a future streaming publisher ## Compatibility Unsigned clients remain on the last complete atomic compatibility snapshot and are never implicitly redirected into DSSE. Clients that explicitly request the signed representation can use the current shard root. A shard-only revision publishes a current bounded query projection and introduces a resetRequired change-stream boundary; later atomic revisions can resume deltas after that boundary. ## Validation - bun run --cwd packages/schema build - 122 focused feed, schema, signing, query/change, shard, cron, and proxy tests passed under Vitest - git diff --check - direct Codex incremental review against feat(feeds): serve signed catalog queries and changes #3160: clean after fixing memory bounds, byte-size routing, locale-stable ordering, timestamp validation, public typing, expiry offsets, and Claw projection parity - deployment-aware Convex codegen remains owned by CI because this worktree has no CONVEX_DEPLOYMENT

[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 22, 2026, 1:32 AM ET / 05:32 UTC.

Summary
The PR adds signed, digest-addressed shard roots and immutable plugin/skill catalog snapshot delivery, including new persistence, HTTP routes, retention jobs, schema artifacts, tests, and protocol documentation.

Reproducibility: not applicable. as a bug reproduction: this is a new producer-side protocol feature. The upgrade risk is source-reproducible because the changed handler returns an unavailable response when signing configuration is missing.

Review metrics: 2 noteworthy metrics.

• Patch surface: 48 files, 7,122 added, 156 removed. The change spans storage schema, publication state, HTTP delivery, generated schema artifacts, workflow behavior, tests, and protocol documentation.
• Public protocol routes: 6 feed routes added or switched. The PR changes existing feed delivery and adds root, shard, query, and change endpoints that must agree with consumers and signer rollout.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🦐 gold shrimp
Result: blocked until real behavior proof is added.

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

Rank-up moves:

• [P1] Add redacted runtime evidence from a real Convex publication through signed root and shard retrieval, including consumer verification output.
• [P1] Document or implement the approved upgrade path for missing production signer configuration and legacy atomic consumers.
• Obtain maintainer confirmation for key distribution, rotation, and the paired consumer rollout.

Proof guidance:

• [P1] Needs real behavior proof before merge: The body lists tests and static checks but no redacted real run showing publication, signed-root retrieval, immutable shard retrieval, and consumer-side digest/signature verification; add that evidence to the PR body before merge. 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.

Risk before merge

• [P1] Existing /v1/feeds/plugins consumers receive 503 after merge if the production signing configuration has not been provisioned and validated.
• [P1] Once the skills snapshot exceeds the atomic limit, existing consumers that do not understand the signed shard-root redirect can no longer consume the legacy JSON response.
• [P1] The signing key identifier, trusted public-key distribution, rotation procedure, and coordinated consumer rollout are protocol/security-boundary decisions that tests alone do not settle.

Maintainer options:

1. Stage the signer activation (recommended)
   Preserve current atomic delivery until the production signer, trusted key distribution, and compatible consumer behavior are demonstrated in a coordinated rollout.
2. Accept a signed-only cutover
   Approve the intentional 503 behavior without signing configuration and the eventual legacy skills redirect as an explicit operator and consumer upgrade requirement.
3. Defer public activation
   Pause the public-route portion until maintainers choose the signing-key and compatibility contract, retaining only work that is independently safe to review.

Next step before merge

• [P1] A maintainer must choose the signed-only activation and consumer-compatibility policy; contributor runtime proof is required and cannot be supplied by an automated repair lane.

Maintainer decision needed

• Question: Should ClawHub make the current public catalog feed fail closed on missing signing configuration and redirect oversized skills consumers to signed shard roots before the matching OpenClaw consumer rollout is merged?
• Rationale: The patch creates a new public protocol and intentionally changes established endpoint behavior during an operator-managed signing-key rollout; maintainer intent is required to choose the compatibility and activation policy.
• Likely owner: giodl73-repo — They authored the linked producer-side protocol stack and can supply the intended rollout and consumer coordination context.
• Options:
  • Stage signed delivery behind compatibility (recommended): Keep the existing atomic endpoint available until production signing configuration and compatible consumers are verified, then activate shard-root delivery in a coordinated rollout.
  • Require signing immediately: Accept that an unconfigured deployment returns 503 and that oversized legacy skills consumers must upgrade to follow signed shard roots.
  • Split the protocol rollout: Land only independently safe storage/schema preparation now and defer public-route activation until the consumer and key-distribution plan are approved.

Security
Cleared: No concrete secret leak, dependency-source change, or new third-party execution path is evident; the remaining concern is secure operational rollout of the new signing trust boundary.

Review findings

• [P1] Preserve feed availability until signing is provisioned — convex/http.ts:176

Review details

Best possible solution:

Stage the signed-feed rollout: provision and verify the signing configuration and consumer trust root first, preserve a documented compatibility path for existing atomic consumers until the matching consumer supports shard roots, then land this producer change with redacted real publication and verification evidence.

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

Not applicable as a bug reproduction: this is a new producer-side protocol feature. The upgrade risk is source-reproducible because the changed handler returns an unavailable response when signing configuration is missing.

Is this the best way to solve the issue?

No, not as an unconditional public-route replacement: a staged signer and consumer rollout is safer than making existing public feed availability depend immediately on a new production secret and protocol consumer.

Full review comments:

• [P1] Preserve feed availability until signing is provisioned — convex/http.ts:176
  This replaces the established plugins-feed handler with signedCatalogFeedV1Http, which returns 503 when CLAWHUB_FEED_SIGNING_CONFIG is absent or invalid. Existing deployments did not require that secret, so merging can take /v1/feeds/plugins offline unless the signer rollout is already guaranteed. Keep a compatible path or include an explicit staged activation with upgrade proof. This was visible at the previously reviewed head and is raised late.
  Confidence: 0.92
  Late finding: first raised on code an earlier review cycle already covered.

Overall correctness: patch is incorrect
Overall confidence: 0.89

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

• add P1: Merging without the required production signer can break an already public feed endpoint for existing consumers.
• add merge-risk: 🚨 availability: Absent or invalid CLAWHUB_FEED_SIGNING_CONFIG causes the public catalog-feed handler to return 503.
• remove P2: Current review triage priority is P1, so this older priority label is no longer current.

Label justifications:

• P1: Merging without the required production signer can break an already public feed endpoint for existing consumers.
• merge-risk: 🚨 compatibility: The existing atomic plugins endpoint becomes signed-only, and oversized skills snapshots transition legacy consumers to a shard-root redirect.
• merge-risk: 🚨 availability: Absent or invalid CLAWHUB_FEED_SIGNING_CONFIG causes the public catalog-feed handler to return 503.
• merge-risk: 🚨 security-boundary: The patch establishes a signed public protocol whose trusted key distribution and rotation policy require explicit rollout ownership.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🦐 gold shrimp.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The body lists tests and static checks but no redacted real run showing publication, signed-root retrieval, immutable shard retrieval, and consumer-side digest/signature verification; add that evidence to the PR body before merge. 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

What I checked:

• Existing-route behavior changes to signed-only delivery: The changed catalog-feed route replaces the previous atomic handler with signedCatalogFeedV1Http, making signing configuration a runtime dependency for the established plugins feed. (convex/http.ts:176, b577bf5da862)
• Missing signer configuration produces an outage response: The new signing handler resolves CLAWHUB_FEED_SIGNING_CONFIG and returns the existing unavailable response when configuration is absent or invalid; this turns an operator rollout omission into a 503 for the public feed. (convex/httpApiV1/catalogFeedSigning.ts:62, b577bf5da862)
• Compatibility boundary is explicitly broadened: The PR description states that oversized skills snapshots replace the legacy atomic response with a no-store 308 redirect to a signed shard root, and that use requires a matching OpenClaw consumer. (specs/hosted-catalog-feed.md:70, b577bf5da862)
• Runtime proof remains absent: The PR body reports focused tests and static checks, but provides no redacted after-fix publication, signed-root retrieval, shard retrieval, or consumer digest-verification evidence; the previous review requested this proof at the same head SHA. (b577bf5da862)
• Related work is still open: The explicitly stacked query/change transport PR remains open at feat(feeds): serve signed catalog queries and changes #3160, while the cross-referenced OpenClaw consumer PR is also open; neither establishes a completed coordinated rollout. (b577bf5da862)

Likely related people:

• giodl73-repo: Authored this PR and the explicitly linked catalog-feed stack, including the open query/change transport work and prior root-feed proposal. (role: protocol-stack author; confidence: medium; commits: c4a95a429495, 60ab2296b046, b577bf5da862; files: convex/catalogFeed.ts, convex/catalogFeedShards.ts, convex/httpApiV1/catalogFeedSigning.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.

Review history (2 earlier review cycles)

• reviewed 2026-07-18T03:32:52.452Z sha 7479e2af4fbdc80a240165b8e8cfdaa95b5b3238 :: needs real behavior proof before merge. :: none
• reviewed 2026-07-21T16:57:02.137Z sha b577bf5 :: needs real behavior proof before merge. :: none

[clawsweeper]

ClawSweeper status: review started.

I am starting a fresh review of this pull request: feat(feeds): publish sharded catalog snapshots This is item 1/1 in the current shard. Shard 3/4.

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.

[github-actions]

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

[github-actions]

Closing due to inactivity.
If this PR should be revived, reopen it with current context and a fresh validation plan.