coulomb/coordination-engine
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
coordination-engine/spec/RssAdapterSpecification.md

44 KiB
Raw Permalink Blame History

RssAdapterSpecification.md

1. Document Status

Document: RssAdapterSpecification.md Project: rss-connect Target Integration: coordination-engine Adapter Contract: AdapterInterfaceSpecification.md v1.0 Status: Draft v1.0 Primary Scope: RSS, Atom, feed publication, feed fetch evidence, and optional WebSub integration as a coordination-engine adapter

2. Purpose

This document specifies how rss-connect models feed-based communication and how it integrates with coordination-engine.

rss-connect is an adapter for pull-based publication and subscription-style communication through RSS, Atom, and related feed technologies. It provides feed item publication, update, removal, feed validation, feed fetch observation where available, optional WebSub hub integration, feed item correlation, and evidence normalization.

Unlike email or SMS, RSS does not primarily push a notification to a known endpoint. RSS makes an item available in a feed that feed readers, aggregators, bots, applications, or users may poll or subscribe to. Therefore, RSS usually provides weak awareness evidence but useful publication, availability, syndication, and machine-readable distribution evidence.

The key design objective is to make feed publication useful within coordination-engine without pretending that publication or fetch equals human awareness.

3. Core Principle

RSS is primarily a publication and availability channel, not a direct recipient-delivery channel.

The adapter MUST distinguish:

feed item publication
feed item update
feed item removal
feed availability
feed fetch by reader/aggregator/system
optional WebSub distribution
link interaction
action-surface interaction from another system
coordination result evidence

RSS feed publication may satisfy some low-assurance broadcast scenarios, but it normally does not prove that a specific participant became aware of the item.

4. Architectural Role

4.1 Standalone Role

As a standalone component, rss-connect provides:

  • RSS feed generation
  • Atom feed generation
  • feed item publication
  • feed item update
  • feed item removal or expiry
  • feed validation
  • feed metadata management
  • feed item correlation
  • feed archive or paging support where applicable
  • fetch analytics where logs are available
  • optional WebSub hub publishing
  • feed health diagnostics
  • normalized feed evidence events
  • feed item timeline and assessment

4.2 coordination-engine Adapter Role

As a coordination-engine adapter, rss-connect provides:

Actions

  • feed.publish_item
  • feed.update_item
  • feed.remove_item
  • feed.expire_item
  • feed.publish_feed
  • feed.register_topic
  • feed.notify_hub where WebSub is used
  • notification.publish as a generic notification action
  • notification.register_tracking_context

Signals

  • feed.item.published
  • feed.item.updated
  • feed.item.removed
  • feed.item.expired
  • feed.item.fetched
  • feed.feed.fetched
  • feed.feed.validated
  • feed.feed.validation_failed
  • feed.hub.notified
  • feed.hub.notification_failed
  • webhook.request.sent
  • webhook.response.accepted
  • webhook.response.rejected
  • interaction.unverified_actor_interaction
  • system.provider.degraded
  • system.provider.unavailable

5. Relationship to coordination-engine

rss-connect does not own:

  • CoordinationCase
  • participant-level success
  • case-level success
  • awareness proof
  • identity-bound interaction
  • payload retrieval from portals
  • payment, signature, contract, or acceptance logic
  • follow-up and escalation policy

rss-connect owns:

  • feed generation
  • feed item publication
  • feed item metadata
  • feed item update and removal
  • feed format validation
  • feed item correlation
  • WebSub publishing where supported
  • feed fetch evidence where observable
  • feed health diagnostics
  • RSS/Atom-native evidence mapping

The boundary rule is:

rss-connect reports publication, availability, feed fetch, and optional subscription-distribution evidence. coordination-engine decides what that means for the coordination case.

6. RSS as Publication, Not Direct Notification

Within coordination-engine, RSS is best understood as a publication channel or low-assurance notification surface.

It may be useful for:

  • public updates
  • low-assurance announcements
  • machine-readable status feeds
  • open information distribution
  • broad, non-personalized broadcast
  • API-adjacent syndication
  • public audit trails
  • delayed or optional awareness
  • low-cost publication fallback
  • feed-based integration with aggregators

RSS is usually not suitable by itself for:

  • high-assurance legal notice
  • proof of participant-specific awareness
  • identity-bound acceptance
  • contract closure
  • payment confirmation
  • confidential document delivery
  • private payload transmission

RSS can point to an action surface, but the result-relevant interaction should normally be observed by another adapter.

Example:

rss-connect:
  feed.item.published
  feed.item.fetched

portal-connect:
  identity.actor_authenticated
  delivery.payload.viewed

coordination-engine:
  participant result satisfied

7. Feed Technology Scope

7.1 RSS 2.0

RSS 2.0 is an XML feed format with a channel and items. Items may include elements such as title, link, description, guid, pubDate, category, author, comments, enclosure, and source. RSS also includes channel-level metadata such as title, link, description, lastBuildDate, pubDate, ttl, and other optional elements.

RSS is widely implemented but has ambiguities and loose semantics. rss-connect MUST avoid overinterpreting RSS reader behavior.

7.2 Atom

Atom is an XML-based syndication format standardized as RFC 4287. Atom feeds contain entries, each with metadata such as id, title, updated, links, authors, summaries, and content. Atom has stronger identity and update semantics than RSS and SHOULD be supported where robust feed item identity and update tracking are important.

7.3 Feed Paging and Archiving

RFC 5005 defines feed paging, archive feeds, and complete feeds. rss-connect MAY support these patterns for scenarios where feed history and reconstructability matter.

7.4 WebSub

WebSub is a W3C recommendation that allows subscribers to receive feed updates through a hub-based publish/subscribe pattern. rss-connect MAY support WebSub to improve timeliness, but WebSub delivery to subscribers still does not prove human awareness.

8. RSS / Feed Lifecycle Model

rss-connect models feed communication as a lifecycle with observable phases.

feed.created
feed.validated
feed.validation_failed
feed.published
feed.updated
feed.unavailable
feed.degraded

item.created
item.rendered
item.render_failed
item.published
item.updated
item.removed
item.expired
item.archived

hub.discovered
hub.notified
hub.notification_failed
hub.subscription_confirmed
hub.distribution_attempted

feed.fetched
item.fetched
item.link_clicked
item.action_surface_opened

The lifecycle is not direct recipient transport. It represents publication and possible downstream consumption.

9. Feed, Item, Attempt, and Subscriber Model

The adapter MUST distinguish at least four layers.

9.1 Feed

A feed is the publication surface.

Feed:
  feed_id: string
  feed_type: rss2 | atom | json_feed | other
  feed_url: string
  title: string
  description: string?
  language: string?
  owner_ref: string?
  visibility: public | private | restricted | internal
  format_version: string?
  self_link: string?
  hub_links:
    - string
  ttl_seconds: integer?
  archive_policy_ref: string?
  created_at: timestamp
  updated_at: timestamp

9.2 FeedItem

A feed item is the published unit.

FeedItem:
  feed_item_id: string
  feed_id: string
  coordination_case_id: string?
  participant_id: string?
  payload_ref: ResourceRef?
  action_surface_ref: ResourceRef?
  item_title: string
  item_summary: string?
  item_content_ref: string?
  canonical_url: string?
  feed_item_url: string?
  guid_or_id: string
  published_at: timestamp
  updated_at: timestamp?
  expires_at: timestamp?
  visibility: public | private | restricted | internal
  state: FeedItemState
  tracking_context: TrackingContext

9.3 FeedPublicationAttempt

A publication attempt represents one attempt to publish or update a feed or item.

FeedPublicationAttempt:
  attempt_id: string
  feed_id: string
  feed_item_id: string?
  action_type: feed.publish_item | feed.update_item | feed.remove_item | feed.publish_feed | feed.notify_hub
  state: FeedPublicationState
  adapter_operation_id: string?
  provider_operation_id: string?
  created_at: timestamp
  completed_at: timestamp?

9.4 FeedSubscriber / FeedConsumer

A feed subscriber or consumer may be known or unknown.

FeedConsumer:
  consumer_id: string?
  consumer_type: human_reader | feed_reader | aggregator | search_engine | bot | system | unknown
  endpoint_ref: EndpointRef?
  user_agent: string?
  ip_address: string?
  known_participant_id: string?
  confidence: low | medium | high
  metadata: object?

Most RSS consumption is not identity-bound. The adapter SHOULD treat feed consumers as unknown unless authenticated feed access, subscriber registration, or other reliable correlation exists.

10. Feed Item States

The adapter SHOULD support these item states:

draft
rendered
render_failed
published
updated
removed
expired
archived
unavailable
unknown

These states are feed-native. They are not coordination result states.

11. Feed Evidence Assessment

rss-connect should provide a feed-native assessment separate from coordination-engine state.

RssEvidenceAssessment:
  feed_item_id: string
  coordination_case_id: string?
  participant_id: string?
  category: success | fail | undef
  subclass: string
  confidence: low | medium | high
  strongest_signal: string?
  evidence_summary:
    - string
  recommended_coordination_interpretation: string?

The assessment categories are adapter-level hints.

11.1 RSS Adapter Success

RSS-level success means the feed channel successfully completed a feed operation.

Possible subclasses:

success.item_published
success.item_updated
success.item_removed
success.feed_valid
success.hub_notified
success.feed_fetched
success.item_fetched
success.link_clicked

Important: These are not automatically coordination success.

success.item_published usually maps to publication availability, not participant awareness.

11.2 RSS Adapter Fail

RSS-level fail indicates feed publication, validation, availability, or hub notification failed.

Subclasses:

fail.feed_invalid
fail.item_render_failed
fail.publish_failed
fail.update_failed
fail.remove_failed
fail.feed_unavailable
fail.hub_notification_failed
fail.hub_rejected
fail.invalid_guid_or_id
fail.invalid_url
fail.payload_reference_invalid
fail.visibility_policy_violation

11.3 RSS Adapter Undef

RSS-level undef is used when publication exists but consumption or awareness is uncertain.

Subclasses:

undef.published_but_unfetched
undef.feed_fetched_by_unknown_consumer
undef.item_fetched_by_unknown_consumer
undef.aggregator_fetch
undef.bot_fetch
undef.feed_reader_fetch
undef.identity_uncertain
undef.awareness_unproven
undef.link_clicked_identity_uncertain
undef.hub_distribution_unknown
undef.cache_interference
undef.conflicting_evidence
undef.channel_degraded

For RSS, undef is the normal state for participant-specific awareness.

12. Detailed Feed Scenario Classification

12.1 Pre-Publication Scenarios

Scenario RSS assessment Normalized event Notes
Missing feed URL fail.publish_failed feed.feed.validation_failed No publication surface
Invalid XML fail.feed_invalid feed.feed.validation_failed Feed unusable
Invalid Atom entry ID / RSS guid fail.invalid_guid_or_id feed.feed.validation_failed Item identity unreliable
Invalid canonical URL fail.invalid_url feed.feed.validation_failed Link target unusable
Payload ref invalid fail.payload_reference_invalid feed.feed.validation_failed or delivery.payload.failed Item points to invalid resource
Render failure fail.item_render_failed feed.feed.validation_failed or action failure Item cannot be generated
Visibility mismatch fail.visibility_policy_violation feed.feed.validation_failed Private item in public feed
Feed store unavailable fail.publish_failed action error Operational failure

12.2 Publication Scenarios

Scenario RSS assessment Normalized event Notes
Item created undef.published_but_unfetched feed.item.published Publication evidence
Item updated success.item_updated feed.item.updated Update evidence
Item removed success.item_removed feed.item.removed Removal evidence
Item expired success.item_removed or expired feed.item.expired No longer active
Feed published success.item_published or feed success feed.item.published or feed-level event Feed available
Feed invalid after publish fail.feed_invalid feed.feed.validation_failed Publication defective
Feed cache not refreshed undef.cache_interference metadata Feed readers may not see update yet
Feed item overwritten/reordered undef.conflicting_evidence metadata Consumer behavior uncertain
Duplicate GUID/ID fail.invalid_guid_or_id feed.feed.validation_failed Readers may ignore or merge item

12.3 Feed Fetch Scenarios

Scenario RSS assessment Normalized event Notes
Feed fetched by unknown client undef.feed_fetched_by_unknown_consumer feed.feed.fetched Weak evidence of consumption
Feed fetched by known aggregator undef.aggregator_fetch feed.feed.fetched May represent many users or none
Feed fetched by known participant system medium evidence feed.feed.fetched Useful for system-to-system
Feed fetched repeatedly weak/medium feed.feed.fetched Could be polling
Feed fetched by bot/crawler undef.bot_fetch feed.feed.fetched Not participant awareness
Conditional GET / cache validation weak feed.feed.fetched with metadata May only confirm cache check
No fetch observed undef.published_but_unfetched none Logging may be incomplete
Fetch log unavailable undef.awareness_unproven none Publication remains only evidence

12.4 Item Fetch / Link Interaction Scenarios

Scenario RSS assessment Normalized event Notes
Item content fetched undef.item_fetched_by_unknown_consumer feed.item.fetched Usually identity uncertain
Enclosure fetched weak/medium delivery evidence delivery.payload.retrieved if payload is enclosure Actor usually unknown
Link clicked undef.link_clicked_identity_uncertain interaction.unverified_actor_interaction Better than feed fetch, still unverified
Link clicked then authenticated portal login RSS event remains weak; portal event is strong Portal adapter provides identity
Link clicked then payload downloaded RSS contributed path evidence; delivery evidence is decisive Delivery adapter closes result
Feed reader prefetches links undef.bot_fetch or cache interference interaction.unverified_actor_interaction or feed fetch Avoid overclaiming
Public search engine indexes item undef.bot_fetch feed/item fetch metadata Not recipient awareness

12.5 WebSub Scenarios

Scenario RSS assessment Normalized event Notes
Hub discovered neutral metadata Capability event
Hub notified successfully success.hub_notified feed.hub.notified Distribution attempt began
Hub notification failed fail.hub_notification_failed feed.hub.notification_failed Push path failed
Subscriber callback accepted weak/medium system evidence webhook.response.accepted System accepted update
Subscriber callback rejected negative system evidence webhook.response.rejected Push delivery failed
Hub status unknown undef.hub_distribution_unknown metadata Common uncertainty
Authenticated WebSub distribution stronger system evidence webhook event with identity metadata Still not human awareness

WebSub improves timeliness and system-level delivery evidence but still usually does not prove human awareness.

13. Adapter-to-Coordination Mapping

13.1 Core Mapping Table

Feed-native event RSS assessment coordination-engine event Coordination interpretation
Feed item created undef.published_but_unfetched feed.item.published Publication evidence
Feed item updated success.item_updated feed.item.updated Update evidence
Feed item removed success.item_removed feed.item.removed Removal evidence
Feed item expired expired feed.item.expired Publication no longer active
Feed valid success.feed_valid feed.feed.validated Feed structurally usable
Feed invalid fail.feed_invalid feed.feed.validation_failed Publication defective
Feed fetched undef.feed_fetched_by_unknown_consumer feed.feed.fetched Weak consumption evidence
Item fetched undef.item_fetched_by_unknown_consumer feed.item.fetched Weak/medium, identity uncertain
Enclosure fetched medium payload evidence delivery.payload.retrieved Actor often unknown
Link clicked undef.link_clicked_identity_uncertain interaction.unverified_actor_interaction Identity uncertain
Hub notified success.hub_notified feed.hub.notified Push notification to hub attempted
Hub failed fail.hub_notification_failed feed.hub.notification_failed Hub path failed
Subscriber callback accepted system evidence webhook.response.accepted System accepted update
Subscriber callback rejected failure webhook.response.rejected System rejected update

13.2 Coordination Undef Subclasses

coordination-engine may derive these uncertainty classes from RSS evidence:

undef.published_but_awareness_unproven
undef.technical_publication_only
undef.no_fetch_observed
undef.feed_fetched_by_unknown_consumer
undef.identity_uncertain
undef.cache_interference
undef.hub_distribution_unknown
undef.channel_suspicious
undef.conflicting_evidence
undef.delivery_pending
undef.escalation_required

RSS evidence commonly produces:

undef.technical_publication_only
undef.feed_fetched_by_unknown_consumer
undef.identity_uncertain
undef.cache_interference

14. Evidence Grading Rules

14.1 Feed Item Published

event_type: feed.item.published
evidence_grade:
  strength: weak
  actor_certainty: none
  authority_certainty: none
  payload_certainty: medium
  interaction_certainty: none
  timing_certainty: high
  channel_certainty: medium
  non_repudiation_strength: low
notes:
  - Item was made available in a feed.
  - Does not prove that a participant fetched, saw, or acted on the item.

14.2 Feed Validated

event_type: feed.feed.validated
evidence_grade:
  strength: medium
  actor_certainty: none
  authority_certainty: none
  payload_certainty: medium
  interaction_certainty: none
  timing_certainty: medium
  channel_certainty: high
  non_repudiation_strength: low
notes:
  - Feed structure is usable by feed clients.
  - Validation is operational evidence, not participant evidence.

14.3 Feed Fetched by Unknown Consumer

event_type: feed.feed.fetched
evidence_grade:
  strength: weak
  actor_certainty: low
  authority_certainty: none
  payload_certainty: low
  interaction_certainty: low
  timing_certainty: medium
  channel_certainty: medium
  non_repudiation_strength: none
notes:
  - A client fetched the feed.
  - The client may be an aggregator, bot, cache, feed reader, or participant system.
  - Does not prove human awareness.

14.4 Item or Enclosure Fetched

event_type: feed.item.fetched
evidence_grade:
  strength: medium
  actor_certainty: low
  authority_certainty: none
  payload_certainty: medium
  interaction_certainty: medium
  timing_certainty: medium
  channel_certainty: medium
  non_repudiation_strength: none
notes:
  - A specific item or enclosure was fetched.
  - Actor identity is usually uncertain unless authenticated access is used.

14.5 Link Click

event_type: interaction.unverified_actor_interaction
evidence_grade:
  strength: medium
  actor_certainty: low
  authority_certainty: none
  payload_certainty: medium
  interaction_certainty: medium
  timing_certainty: medium
  channel_certainty: medium
  non_repudiation_strength: none
notes:
  - A link associated with the feed item was followed.
  - Stronger evidence should come from the action surface or identity adapter.

14.6 WebSub Hub Notified

event_type: feed.hub.notified
evidence_grade:
  strength: medium
  actor_certainty: none
  authority_certainty: none
  payload_certainty: medium
  interaction_certainty: none
  timing_certainty: high
  channel_certainty: medium
  non_repudiation_strength: low
notes:
  - Hub notification was attempted or accepted.
  - Subscriber delivery and human awareness are not guaranteed.

14.7 Subscriber Callback Accepted

event_type: webhook.response.accepted
evidence_grade:
  strength: medium
  actor_certainty: medium
  authority_certainty: low
  payload_certainty: medium
  interaction_certainty: low
  timing_certainty: high
  channel_certainty: high
  non_repudiation_strength: low
notes:
  - A subscriber system accepted a WebSub delivery callback.
  - This may be strong system-to-system evidence but not human awareness.

15. Feed Validation Requirements

rss-connect SHOULD validate generated feeds before publication.

Validation checks SHOULD include:

well-formed XML
valid RSS or Atom structure
required channel/feed metadata present
item has required title/description or Atom-required fields
stable guid or Atom id present
valid link URLs
valid pubDate / updated timestamps
no duplicate active GUID/ID unless update semantics require it
visibility policy respected
payload/action-surface links valid
feed size within configured limits
character encoding valid

For Atom, entries should use stable IDs and update timestamps consistent with Atom semantics.

For RSS, GUIDs should be stable and not accidentally regenerated for the same logical item unless a new item is intended.

16. Adapter Descriptor

rss-connect MUST expose an AdapterDescriptor compatible with AdapterInterfaceSpecification.md v1.0.

adapter_id: rss-connect.default
adapter_name: rss-connect
adapter_version: 1.0.0
adapter_contract_version: 1.0
adapter_types:
  - notification
  - communication
  - feed
provider_family: feed
provider_name: rss-atom
deployment_mode: external
supported_channels:
  - rss
  - atom
  - websub
supported_endpoint_types:
  - rss_feed
  - atom_feed
  - websub_topic
  - webhook_url
supported_actions:
  - action_type: feed.publish_item
    mode: async
    idempotency_required: true
  - action_type: feed.update_item
    mode: async
    idempotency_required: true
  - action_type: feed.remove_item
    mode: async
    idempotency_required: true
  - action_type: feed.notify_hub
    mode: async
    idempotency_required: true
  - action_type: notification.publish
    mode: async
    idempotency_required: true
  - action_type: notification.register_tracking_context
    mode: sync
    idempotency_required: true
emitted_event_types:
  - feed.item.published
  - feed.item.updated
  - feed.item.removed
  - feed.item.expired
  - feed.item.fetched
  - feed.feed.fetched
  - feed.feed.validated
  - feed.feed.validation_failed
  - feed.hub.notified
  - feed.hub.notification_failed
  - webhook.request.sent
  - webhook.response.accepted
  - webhook.response.rejected
  - interaction.unverified_actor_interaction
  - system.provider.degraded
  - system.provider.unavailable
evidence_profile:
  strongest_evidence_level: weak_to_medium
  can_prove_human_awareness: false
  can_prove_payload_delivery: false
  can_prove_identity: false
identity_profile:
  identity_strength: none_to_low
  authority_strength: none
limitations:
  - Feed publication does not prove participant awareness.
  - Feed fetches are often performed by aggregators, bots, caches, or feed readers.
  - RSS/Atom readers may poll at unpredictable intervals.
  - Feed clients may cache, reorder, merge, or ignore items.
  - GUID or ID stability is essential for reliable item tracking.
  - WebSub improves timeliness but does not prove human awareness.
  - Public feeds are generally unsuitable for confidential payloads.

17. Action Request Handling

17.1 feed.publish_item

feed.publish_item publishes a new feed item.

Required fields:

request_id
action_type
coordination_case_id
payload_ref or content
feed target
tracking_context
idempotency_key
requested_at

Example:

request_id: req_001
action_type: feed.publish_item
coordination_case_id: case_123
participant_id: null
channel: rss
target_endpoint:
  endpoint_type: rss_feed
  value: https://example.com/feed.xml
content:
  subject: New document available
  body_text: A new document is available in the portal.
  action_links:
    - link_id: portal_link
      purpose: open_action_surface
      url: https://portal.example.com/access/abc
      tokenized: false
      requires_authentication: true
payload_ref:
  ref_type: coordination_payload
  ref_id: payload_777
tracking_context:
  correlation_id: corr_789
  coordination_case_id: case_123
  payload_id: payload_777
  action_surface_id: portal_001
idempotency_key: case_123:rss:feeditem:payload_777
requested_at: 2026-01-01T12:00:00Z

17.2 Action Result

The adapter returns:

request_id: req_001
adapter_id: rss-connect.default
accepted: true
action_state: accepted
adapter_operation_id: rssop_001
initial_events:
  - event_type: feed.item.published
received_at: 2026-01-01T12:00:01Z

This result proves publication attempt success, not participant awareness.

18. Feed Format Model

rss-connect SHOULD support a provider-neutral feed model and render to RSS and Atom.

SyndicationFeed:
  feed_id: string
  feed_type: rss2 | atom
  title: string
  description: string?
  site_url: string
  feed_url: string
  language: string?
  updated_at: timestamp
  ttl_seconds: integer?
  hub_links:
    - string
  entries:
    - SyndicationEntry

SyndicationEntry:
  entry_id: string
  stable_id: string
  title: string
  summary: string?
  content_ref: string?
  canonical_url: string?
  published_at: timestamp
  updated_at: timestamp?
  authors:
    - string
  categories:
    - string
  enclosures:
    - FeedEnclosure
  metadata: object?

FeedEnclosure:
  url: string
  mime_type: string?
  length_bytes: integer?
  payload_ref: ResourceRef?

RSS Rendering Notes

RSS rendering should map:

stable_id → guid
published_at → pubDate
canonical_url → link
summary/content → description
feed updated_at → lastBuildDate
ttl_seconds → ttl, where supported

Atom Rendering Notes

Atom rendering should map:

stable_id → atom:id
updated_at → atom:updated
published_at → atom:published, if used
canonical_url → atom:link rel="alternate"
feed_url → atom:link rel="self"
summary/content → atom:summary or atom:content

19. Fetch Observation Model

Fetch observation is optional and depends on access to server logs, reverse proxy logs, analytics, authenticated feed endpoints, or WebSub subscriber data.

FeedFetchEvent:
  fetch_event_id: string
  feed_id: string
  feed_item_id: string?
  occurred_at: timestamp
  request_url: string
  ip_address: string?
  user_agent: string?
  http_method: string?
  status_code: integer?
  cache_status: hit | miss | revalidated | unknown
  conditional_request: boolean?
  consumer_classification: human_reader | feed_reader | aggregator | bot | system | unknown
  participant_id: string?
  confidence: low | medium | high

Fetch observation MUST be classified conservatively.

A feed fetch by a feed reader is not the same as a human reading the item.

20. Consumer Classification

rss-connect SHOULD classify feed consumers where possible.

Possible consumer classifications:

known_participant_system
known_internal_system
feed_reader
aggregator
bot
crawler
search_engine
cache
websub_hub
unknown

Classification hints:

  • user-agent
  • IP address
  • authenticated feed access
  • tokenized feed URLs
  • WebSub subscription metadata
  • known internal client IDs
  • request pattern
  • HTTP headers
  • referrer
  • access logs
  • API key or bearer token where used

Unless authenticated or strongly correlated, actor certainty should remain low.

21. WebSub Model

If WebSub is supported, rss-connect SHOULD model hubs, topics, and subscriber callbacks.

WebSubTopic:
  topic_url: string
  feed_id: string
  hub_urls:
    - string
  lease_seconds: integer?

WebSubNotification:
  notification_id: string
  topic_url: string
  hub_url: string
  feed_item_id: string?
  state: created | sent | accepted | rejected | failed | unknown
  occurred_at: timestamp
  raw_response_ref: string?

WebSub events should map to:

feed.hub.notified
feed.hub.notification_failed
webhook.request.sent
webhook.response.accepted
webhook.response.rejected

WebSub improves distribution mechanics but does not change the core evidence rule: hub or subscriber delivery is not human awareness.

22. Publication and Visibility Model

rss-connect MUST protect against accidental leakage of private payloads.

FeedVisibilityPolicy:
  visibility: public | private | restricted | internal
  allowed_payload_sensitivity:
    - public
    - internal
    - confidential
  require_authentication: boolean
  allow_tokenized_urls: boolean
  allow_payload_enclosures: boolean
  allow_inline_content: boolean

Public feeds SHOULD NOT contain confidential payloads.

For confidential coordination cases, feed items should normally contain only non-sensitive notification text and a link to an authenticated action surface.

23. Channel Health

rss-connect SHOULD expose feed channel health.

RssChannelHealth:
  feed_id: string
  status: healthy | degraded | failing | unknown
  feed_url: string
  last_successful_publish_at: timestamp?
  last_successful_validation_at: timestamp?
  last_fetch_observed_at: timestamp?
  validation_status: valid | invalid | unknown
  availability_status: available | unavailable | degraded | unknown
  hub_status: healthy | degraded | unavailable | not_configured | unknown
  known_degradations:
    - string

Health-related normalized events:

system.provider.degraded
system.provider.unavailable
system.adapter.health_changed
feed.feed.validation_failed

24. Security Requirements

rss-connect MUST:

  • validate feed content before publication
  • prevent publication of private payloads into public feeds unless explicitly configured
  • preserve idempotency
  • avoid duplicate feed items for repeated idempotency keys
  • protect credentials for private feed publishing or WebSub hubs
  • verify WebSub callbacks or hub interactions where applicable
  • avoid leaking tracking tokens in public feed content unless policy allows it
  • sanitize feed item content
  • avoid XML injection and malformed feed generation
  • support tenant or feed separation where applicable

25. Privacy Requirements

rss-connect SHOULD:

  • store content references instead of full content where possible
  • support metadata-only mode
  • support redaction of fetch logs
  • avoid collecting unnecessary IP/user-agent data
  • support configurable retention of raw fetch data
  • distinguish public-feed publication from participant-specific tracking
  • avoid participant-specific data in public feed URLs
  • support deletion or anonymization workflows where applicable

26. Reliability Requirements

rss-connect MUST support:

  • idempotent publication requests
  • duplicate feed item detection
  • stable item IDs
  • out-of-order update handling
  • feed validation failures
  • hub notification retry where configured
  • degraded feed storage handling
  • cache-related uncertainty
  • correlation preservation
  • dead-letter handling for unprocessable events

A repeated feed.publish_item with the same idempotency key MUST NOT produce duplicate feed entries.

27. Raw Event Preservation

rss-connect SHOULD preserve raw publication, validation, fetch, and hub events or references to them.

RawFeedEventRef:
  raw_event_id: string
  source: adapter | feed_store | web_server | reverse_proxy | hub | validator
  storage_ref: string?
  received_at: timestamp
  redacted: boolean

Normalized events should reference raw event data where available:

raw_event_ref: raw_feed_event_123

28. Minimal API Surface

rss-connect SHOULD expose a headless API.

28.1 Adapter Contract API

Required conceptual operations:

GET /adapter/descriptor
GET /adapter/health
POST /adapter/actions
POST /adapter/events/provider
GET /adapter/events
GET /adapter/feed-items/{id}/timeline
GET /adapter/feed-items/{id}/assessment

The actual transport may differ, but these conceptual operations should exist.

28.2 Standalone API

Useful standalone operations:

POST /feeds
GET /feeds/{id}
POST /feeds/{id}/items
PUT /feeds/{id}/items/{item_id}
DELETE /feeds/{id}/items/{item_id}
POST /feeds/{id}/validate
GET /feeds/{id}/health
GET /feeds/{id}/items/{item_id}/timeline
GET /feeds/{id}/items/{item_id}/assessment
POST /feeds/{id}/websub/notify
GET /feeds/{id}/fetch-events

29. Example End-to-End Flows

29.1 Public Update Broadcast

  1. coordination-engine creates a broadcast coordination case.
  2. Policy selects RSS as a low-assurance publication channel.
  3. coordination-engine sends feed.publish_item to rss-connect.
  4. rss-connect renders and validates feed item.
  5. rss-connect publishes the item.
  6. rss-connect emits feed.item.published.
  7. Feed readers eventually fetch the feed.
  8. rss-connect emits feed.feed.fetched where observable.
  9. If the intended result only requires public publication, coordination-engine may mark the communication result satisfied.
  10. If participant awareness is required, the case remains unresolved until stronger evidence appears.

29.2 Feed Item to Authenticated Portal

  1. rss-connect publishes a feed item with a link to an authenticated action surface.
  2. A user or feed reader follows the link.
  3. rss-connect emits interaction.unverified_actor_interaction.
  4. portal-connect records authenticated login.
  5. portal-connect records payload view/download.
  6. coordination-engine marks the relevant participant complete based on portal evidence.

29.3 WebSub Distribution

  1. rss-connect publishes a feed item.
  2. rss-connect notifies a WebSub hub.
  3. Hub accepts notification.
  4. rss-connect emits feed.hub.notified.
  5. Subscriber callback acceptance may be observed.
  6. rss-connect emits webhook.response.accepted.
  7. coordination-engine treats this as system-level distribution evidence, not human awareness.

29.4 Invalid Feed Publication

  1. coordination-engine requests feed item publication.
  2. Rendered item has invalid XML or duplicate unstable ID.
  3. rss-connect rejects publication.
  4. rss-connect emits feed.feed.validation_failed.
  5. coordination-engine triggers correction or alternate channel.

30. Provider / Storage Implementation Guidance

rss-connect may publish feeds through:

static file generation
object storage
web server file publication
CMS integration
headless content API
database-backed feed service
WebSub hub integration
reverse proxy / CDN integration

The implementation SHOULD avoid binding the core model to one storage backend.

Provider-specific modules should map to the feed-native model first, then to normalized coordination events.

Storage/web/server event
→ feed-native event
→ RssEvidenceAssessment
→ EvidenceEvent for coordination-engine

31. Message Stream / Feed Separation

rss-connect SHOULD support separate feeds for different purposes.

Recommended feed streams:

public_news
status_updates
system_alerts
coordination_notifications
legal_or_high_assurance_public_notices
internal_machine_feed```

High-assurance or sensitive notifications SHOULD NOT share public feeds unless explicitly intended.

Feed separation may affect:

* visibility
* caching
* access controls
* item retention
* archive policy
* WebSub hub configuration
* payload link policy
* identity and tracking policy

## 32. Legal and Compliance Disclaimer

`rss-connect` does not by itself provide legal proof of participant-specific delivery, awareness, acceptance, signature, payment, or contract closure.

It provides evidence from feed publication and feed consumption channels.

Scenario-specific applications and `coordination-engine` policies may treat public publication as sufficient for some use cases, but that is a policy decision outside `rss-connect`.

The adapter MUST avoid naming feed events in ways that imply participant-specific notification success.

Use:

```text
feed.item.published
feed.feed.fetched

Avoid:

recipient_notified
participant_aware
legal_notice_completed

33. MVP Scope

The first useful version of rss-connect should implement:

  1. Adapter descriptor.
  2. Adapter health endpoint.
  3. feed.publish_item.
  4. feed.update_item.
  5. feed.remove_item.
  6. Idempotent publication request handling.
  7. RSS 2.0 feed rendering.
  8. Basic Atom feed rendering if feasible.
  9. Feed validation.
  10. Stable GUID/ID handling.
  11. Evidence event generation.
  12. Feed item timeline.
  13. Feed item assessment.
  14. Optional basic fetch event ingestion from web server logs.
  15. Mapping to AdapterInterfaceSpecification.md v1.0.

MVP Required Feed Events

feed.item.published
feed.item.updated
feed.item.removed
feed.feed.validated
feed.feed.validation_failed
feed.feed.fetched
feed.item.fetched
interaction.unverified_actor_interaction
system.provider.degraded
system.provider.unavailable

MVP Acceptance Criteria

The MVP is acceptable when it can:

  1. Accept a coordination-compatible feed publication request.
  2. Render a valid RSS feed item.
  3. Preserve correlation and idempotency.
  4. Avoid duplicate entries for duplicate idempotency keys.
  5. Emit feed.item.published.
  6. Validate feed output.
  7. Classify publication as weak publication evidence, not awareness.
  8. Optionally ingest fetch logs and emit weak fetch evidence.
  9. Provide a feed item timeline.
  10. Provide an RSS evidence assessment.
  11. Integrate with coordination-engine without overclaiming participant awareness.

34. Future Extensions

Potential future capabilities:

  • Atom-first robust feed generation
  • JSON Feed support
  • RFC 5005 archive and paging support
  • WebSub hub publishing
  • WebSub subscriber endpoint support
  • authenticated private feeds
  • tokenized participant-specific feeds
  • feed reader fingerprinting
  • advanced fetch analytics
  • feed archive reconstruction
  • CDN cache integration
  • public notice publication pattern
  • internal system-to-system feed pattern
  • multilingual feed generation
  • feed signing
  • feed integrity manifests
  • feed diffing
  • per-feed retention policies
  • feed-to-portal conversion tracking
  • AI-assisted feed content generation
  • monitoring for feed reader compatibility

35. Non-Goals

rss-connect is not:

  • a direct messaging platform
  • a high-assurance notification channel by itself
  • a confidential document delivery system by default
  • a proof-of-awareness system
  • a CRM
  • a full workflow engine
  • a portal
  • a payment system
  • a signature system
  • the owner of coordination case success

It may integrate with such systems or be used by them.

36. Summary

rss-connect models RSS, Atom, and related feed technologies as publication and pull-based communication channels.

Its job is to:

  • publish feed items
  • update or remove feed items
  • validate feeds
  • preserve stable item identity
  • optionally observe feed fetches
  • optionally notify WebSub hubs
  • normalize feed evidence
  • expose feed diagnostics
  • integrate cleanly with coordination-engine

The key rule is:

RSS events are publication and weak consumption evidence, not participant-specific result satisfaction. rss-connect reports feed-channel facts and uncertainty. coordination-engine evaluates intended results.

Reference in New Issue View Git Blame Copy Permalink