# 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:

```text
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:

```text
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.

```text
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.

```yaml
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.

```yaml
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.

```yaml
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.

```yaml
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:

```text
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.

```yaml
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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:

```text
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.

```yaml
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:

```text
request_id
action_type
coordination_case_id
payload_ref or content
feed target
tracking_context
idempotency_key
requested_at
```

Example:

```yaml
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:

```yaml
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.

```yaml
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
```

```yaml
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?
```

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

### RSS Rendering Notes

RSS rendering should map:

```text
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:

```text
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.

```yaml
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:

```text
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.

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

```yaml
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:

```text
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.

```yaml
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.

```yaml
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:

```text
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.

```yaml
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:

```yaml
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:

```text
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:

```text
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:

```text
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.

```text
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:

```text
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:

```text
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

```text
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.