RFC 0009: align Hosted Feed v1 specifications

[giodl73-repo]

Summary

Last-call correction and scale pass for RFC 0009 before additional publishers and clients depend on it.

• align Hosted Feed v1 with the shipped strict ClawHub catalog schema and marketplaces.* OpenClaw configuration
• specify standard DSSE envelopes, verifier dispatch, expected feed-id binding, threshold behavior, and out-of-band key rotation
• define publisher feeds over ClawHub's stable publisher identity, coherent revisions, bounded pagination, and signed projections
• define signed shard roots, immutable digest-addressed shards, signed query pages, and signed changed-since pages with tombstones
• make local item watches and verified update history the v1 notification baseline while keeping hosted synchronization optional
• separate the required publisher-feed path from optional ClawHub social discovery

Current merge lanes

1. Signed-feed activation: fix(feeds): accept standard DSSE envelopes openclaw#110037, fix(marketplaces): allow trusted feed key rotation openclaw#108342, feat(feeds): add dormant catalog signing foundation clawhub#3005, key provisioning, then feat: bind signed ClawHub default feed trust openclaw#101981.
2. Publisher feeds, first product lane: ClawHub #2948, #3116, #3117; OpenClaw #109305, #109340, #109378, #109397, #109461, #109584.
3. Main-catalog scale, second product lane: ClawHub #3149, #3160, #3163; OpenClaw #110250.
4. Client-first watches: OpenClaw #110438. Its Control UI follow-up is intentionally not authored until the storage/CLI boundary is accepted.
5. Optional ClawHub social discovery: #2949, #2950, #2958. Registry export #2953 and hosted inbox #3171 remain parked.

The implementation inventory is informative rather than normative. Closed consolidation PRs are no longer listed.

Protocol boundaries

• ClawHub publishers are the public identity for both people and organizations; there is no parallel public account-feed identity.
• Publisher discovery payloads are not install catalogs and cannot grant install authority.
• Each feed class and representation has a distinct payload type and expected identity binding.
• Complete large feeds use signed roots plus immutable shards.
• Interactive search uses signed revision-bound query pages.
• Incremental refresh uses signed contiguous change ranges, tombstones, and explicit reset-required responses.
• Watches are evaluated only after signed state is verified and accepted; notifications never install or update content.

Validation

• compared catalog fields with ClawHub CatalogFeedSchema
• compared publisher fields with the #2948 PublisherFeedSchema
• compared envelope parsing with DSSE 1.0.2 and the OpenClaw verifier
• compared shard-root, expiry, digest, and fallback rules with ClawHub #3163 and OpenClaw #110250
• verified local Markdown links and balanced code fences across all five RFC/spec documents
• verified no stale references remain to the seven closed consolidation PRs
• git diff --check
• codex review --uncommitted was attempted on the final correction but timed out after three minutes without output

A final-head deployed OpenClaw-ClawHub interoperability transcript is still outstanding; this update does not claim that proof.

Review request

This is the Hosted Feed v1 last-call contract review. Please flag wire-format, pagination, query, delta, local-watch, optional hosted-sync, or trust-model objections while the linked producer and consumer stacks converge. Protocol-owner sign-off and final-head interoperability proof remain explicit merge gates.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 1, 2026, 4:36 PM ET / 20:36 UTC.

ClawSweeper review

What this changes

The PR revises RFC 0009 and four Hosted Feed v1 specifications, adding signed sharded distribution, query and change refresh rules, publisher-feed alignment, DSSE trust requirements, and client-side watch semantics.

Merge readiness

⚠️ Ready for maintainer review - 5 items remain

Keep this PR open. Current main does not contain the new distribution/query addendum or the revised protocol boundaries, so the central work is still necessary; however, the RFC deliberately establishes compatibility- and trust-sensitive contracts while its producer/client lanes are still converging, so protocol-owner approval and final-head interoperability evidence are required before merge.

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

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The documentation patch is substantial and internally structured, but maintainer confidence remains limited until protocol owners ratify the contract and producer/client interoperability is demonstrated at the final head.
Proof confidence	🌊 off-meta tidepool	Not applicable: All five changed paths are RFC/specification documents, so the external runtime-proof gate does not apply; the PR's own final-head interoperability transcript remains a protocol merge gate and should be redacted for any sensitive endpoints or credentials.
Patch quality	🦐 gold shrimp (3/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: All five changed paths are RFC/specification documents, so the external runtime-proof gate does not apply; the PR's own final-head interoperability transcript remains a protocol merge gate and should be redacted for any sensitive endpoints or credentials.
Evidence reviewed	5 items	Current main lacks the proposed distribution contract: Current main has no hosted-feed-distribution-v1-spec.md; the existing core specification explicitly keeps signed envelopes and publisher feeds outside its scope, so the PR's central signed distribution and publisher-query work is not already implemented. Unique proposed specification surface: The PR adds a 463-line distribution addendum covering signed roots, immutable shards, revision-bound query pages, contiguous change pages, and watches; these are substantive new protocol definitions rather than obsolete documentation churn. Current main provenance: The current baseline sidecar addenda were introduced on main by the available history commit, making Gio Della-Libera the clearest current-main routing candidate for the RFC 0009 addendum surface.
Findings	None	None.
Security	None	None.

How this fits together

Hosted Feed v1 is the contract between feed publishers such as ClawHub and OpenClaw clients that discover, verify, refresh, and use plugin and skill catalogs. These RFC documents define the signed transport and feed representations that downstream publisher APIs, client configuration, and update notifications must implement consistently.

flowchart LR
  A[Feed Publisher] --> B[Signed Feed Envelope]
  B --> C[Client Trust Verification]
  C --> D[Catalog or Publisher Representation]
  D --> E[Query and Change Refresh]
  E --> F[Verified Local State]
  F --> G[Watches and Notifications]

Loading

Decision needed

Question	Recommendation
Should RFC 0009 adopt these signed distribution, publisher-feed, and local-watch contracts as the v1 reference while the linked producer and consumer implementations are still converging?	Ratify after interoperability proof: Obtain protocol-owner sign-off and a redacted final-head OpenClaw–ClawHub interoperability transcript before merging the RFC contract.

Why: The patch is documentation-only and has no discrete line-level defect, but it establishes external compatibility and security semantics that cannot be selected safely by an automated review.

Before merge

• Add real behavior proof - Not applicable: All five changed paths are RFC/specification documents, so the external runtime-proof gate does not apply; the PR's own final-head interoperability transcript remains a protocol merge gate and should be redacted for any sensitive endpoints or credentials.
• Resolve merge risk (P2) - The PR defines verification, payload-type, pagination, reset, and fallback contracts that OpenClaw and ClawHub implementations may depend on; merging before a final-head interoperability transcript risks producer/client divergence.
• Resolve merge risk (P1) - The DSSE trust and fail-closed rules establish a security boundary, so protocol owners need to confirm that the documented verifier dispatch, identity binding, threshold behavior, and key-rotation semantics match the implementation lanes before this becomes the reference contract.
• Complete next step (P2) - No mechanical repair is indicated; protocol-owner direction and cross-repository interoperability evidence are the remaining merge gates.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Specification scope	5 RFC/spec files affected; 1 new addendum	The PR changes the core contract plus trust, publisher, and distribution sidecars, so cross-document consistency matters more than an isolated wording review.
Protocol churn	1,335 added, 872 removed	The 2,207-line documentation diff materially redefines a draft interoperable protocol rather than making a small editorial correction.

Root-cause cluster

Relationship: canonical
Canonical: #39
Summary: This PR is the primary RFC contract update; the earlier merged addendum PR supplied the baseline documents but does not contain the remaining distribution and alignment work.

Members:

• partial_overlap: Add hosted feed trust and account-feed specs #38 - The merged PR created the trust and account-feed addendum baseline that this PR substantially revises and extends with distribution and publisher-feed rules.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge-risk options

Maintainer options:

1. Validate the contract end to end (recommended)
   Before merge, obtain protocol-owner approval and a final-head producer/client transcript covering signed verification, expected identity binding, and at least one query or refresh representation.
2. Pause until the implementation lanes settle
   Leave the draft contract open if its payload types, pagination, reset, or key-rotation rules remain unsettled across OpenClaw and ClawHub.

Technical review

Best possible solution:

Land a protocol-owner-ratified Hosted Feed v1 contract only after a final-head OpenClaw–ClawHub interoperability transcript exercises signed envelope verification, a publisher or catalog projection, and a refresh path against the agreed wire shapes.

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

Not applicable: this PR changes RFC and protocol-specification documents rather than an executable bug path. The needed merge evidence is cross-repository interoperability validation, not a bug reproduction.

Is this the best way to solve the issue?

Unclear: the proposed document split is coherent and current main lacks the distribution contract, but protocol owners must confirm that the final wire rules match the converging producer and client implementations before it becomes the v1 reference.

AGENTS.md: found and applied where relevant.

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

Labels

Label justifications:

• P2: This is a substantial but non-emergency draft protocol change with bounded compatibility and trust implications.
• merge-risk: 🚨 compatibility: The new payload types, pagination, change, and fallback rules can affect independently developed feed publishers and OpenClaw clients.
• merge-risk: 🚨 security-boundary: The RFC specifies DSSE verification, trusted-key dispatch, identity binding, signature thresholds, and key rotation behavior.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: All five changed paths are RFC/specification documents, so the external runtime-proof gate does not apply; the PR's own final-head interoperability transcript remains a protocol merge gate and should be redacted for any sensitive endpoints or credentials.

Evidence

What I checked:

• Current main lacks the proposed distribution contract: Current main has no hosted-feed-distribution-v1-spec.md; the existing core specification explicitly keeps signed envelopes and publisher feeds outside its scope, so the PR's central signed distribution and publisher-query work is not already implemented. (rfcs/0009/hosted-feed-v1-spec.md:26, af708f0ddb6f)
• Unique proposed specification surface: The PR adds a 463-line distribution addendum covering signed roots, immutable shards, revision-bound query pages, contiguous change pages, and watches; these are substantive new protocol definitions rather than obsolete documentation churn. (rfcs/0009/hosted-feed-distribution-v1-spec.md:1, e4b78a524d4b)
• Current main provenance: The current baseline sidecar addenda were introduced on main by the available history commit, making Gio Della-Libera the clearest current-main routing candidate for the RFC 0009 addendum surface. (rfcs/0009/signed-feed-trust-v1-spec.md:1, 2d213ae23462)
• Documentation validation: The submitted documentation diff passes whitespace validation; all five changed paths are RFC/specification documents, so the external runtime-proof gate does not apply. (rfcs/0009/hosted-feed-distribution-v1-spec.md:1, e4b78a524d4b)
• History inspection limitation: Available current commits establish the immediate addendum provenance, but deeper git log --follow and older blame traversal could not retrieve promisor objects because the checkout could not resolve GitHub during this review; ownership confidence is therefore limited to the available history.

Likely related people:

• Gio Della-Libera: Available current-main history shows Gio Della-Libera authored the RFC 0009 trust/addendum series and the merged addendum baseline that this PR revises. (role: recent addendum author and current-main area contributor; confidence: medium; commits: f9ac10e91384, 2d213ae23462; files: rfcs/0009-hosted-feed-v1-spec.md, rfcs/0009/signed-feed-trust-v1-spec.md, rfcs/0009/clawhub-account-feeds-v1-spec.md)

Rank-up moves

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

• Add a redacted final-head OpenClaw–ClawHub interoperability transcript covering signature verification and one signed projection or refresh flow.
• Record protocol-owner sign-off or the accepted dispositions for the payload-type, pagination, reset, and key-rotation choices in the PR body.

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 (20 earlier review cycles; latest 8 shown)

• reviewed 2026-07-18T13:51:56.146Z sha be1026d :: needs real behavior proof before merge. :: none
• reviewed 2026-07-18T15:59:12.782Z sha e4b78a5 :: needs real behavior proof before merge. :: none
• reviewed 2026-07-29T20:23:30.616Z sha e4b78a5 :: needs real behavior proof before merge. :: none
• reviewed 2026-07-30T08:38:52.865Z sha e4b78a5 :: needs real behavior proof before merge. :: none
• reviewed 2026-07-30T14:35:06.273Z sha e4b78a5 :: needs real behavior proof before merge. :: none
• reviewed 2026-07-31T17:58:06.208Z sha e4b78a5 :: needs real behavior proof before merge. :: none
• reviewed 2026-07-31T19:47:32.616Z sha e4b78a5 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-01T15:20:35.162Z sha e4b78a5 :: needs real behavior proof before merge. :: none