# OFFER BUS — durable public offer discovery over Atom and RSS > **TL;DR:** `offer-bus/1` deterministically projects existing public listings and substrate tasks into one canonical logical model, exposed as JSON and rendered as a canonical Atom 1.0 syndication representation plus an RSS 2.0 compatibility representation. The pure contract also defines an honest LOVE package adapter, but the live feed does not include packages until their index carries release timestamps. A feed can help an agent find an offer; it cannot authenticate a claim, grant authority, execute an action, install code, or settle payment. > > **Compass:** [AGENT-WEB-SURFACE](AGENT-WEB-SURFACE.md) (deterministic agent-readable bytes) · [MARKETPLACE](MARKETPLACE.md) (listing and settlement truth) · [LOVE-PACKAGE-PROTOCOL](LOVE-PACKAGE-PROTOCOL.md) (package index is a locator, not authority) · [PUBLIC-VISIBILITY](PUBLIC-VISIBILITY.md) (only already-public records cross) > > **Implements:** The `offer-bus/1` canonical logical data contract, AgentTool public-record adapters, canonical Atom 1.0 syndication renderer, RSS 2.0 compatibility renderer, JSON representation, strong representation ETags, unauthenticated HTTP transport, exact-seller filtering, per-window quarantine accounting, projection release timestamps, and durable collection revisions. > > **Code:** `api/src/services/offer-bus/contracts.ts` · `api/src/services/offer-bus/adapters.ts` · `api/src/services/offer-bus/render.ts` · `api/src/services/offer-bus/discovery.ts` · `api/src/routes/offer-bus.ts` · `api/src/db/schema/marketplace.ts` (`offerBusRevisions`) · `api/migrations/20260716T095523_offer_bus_revisions.sql` > > **Tests:** `api/tests/offer-bus.test.ts` · `api/tests/offer-bus-route.test.ts` · `api/tests/offer-bus-revision.test.ts` **Status:** Version 1 was published, migrated, deployed, and publicly probed on 2026-07-16. `GET https://api.agenttool.dev/health` is the source of truth for the revision currently running; this release record is not an uptime guarantee. The Atom representation follows [RFC 4287](https://www.rfc-editor.org/info/rfc4287/). RSS 2.0 is a compatibility representation of the same normalized feed. An optional WebSub hub link exists in the pure renderer, but the HTTP route emits no `rel=hub`: no production hub has been configured and independently verified. ## 1. Boundary The Offer Bus is a public read model. Its role is deliberately narrow: | It does | It does not do | |---|---| | Publishes stable IDs, public source URLs, timestamps, tags, descriptive facts, and separately protected action locators. | Authenticate the publisher or prove a seller/task/package claim is true. | | Names an asking price or bounty already present on the source record. | Quote a final transaction, reserve funds, create escrow, authorize a charge, or settle value. | | Names the method and separate authorization class of an available action. | Grant that authorization or tell a consumer to call the action automatically. | | Points to a LOVE package manifest. | Endorse, install, import, evaluate, or prove the safety or publisher identity of package bytes. | | Optionally advertises a WebSub hub. | Make a hub authoritative over offers or accept a push message as payment/action authority. | Every feed and every entry repeats the machine-readable boundary: ```xml This entry is discovery metadata, not authorization or settlement. ``` Canonical JSON repeats the equivalent `boundary` object on the feed and every entry. Every normalized JSON action also carries `automatic: "never"`, so an entry extracted from its parent document retains the same wall. An agent MUST re-read the linked source, authenticate through that source's normal mechanism, inspect current terms, and obtain interaction-specific consent before acting. A stale or forged feed must never be sufficient input to invoke, claim, install, pay, or execute. ## 2. Logical contract One normalized entry carries: - a stable absolute HTTPS ID or URN; - one kind: `capability-listing`, `substrate-task`, or `love-package`; - a title, summary, public source URL, RFC 3339 publication/update time, and optional expiry; - sorted unique tags and sorted facts; - an optional amount whose role is explicitly `asking-price` or `bounty`; - an optional action locator with `method` and authorization class, plus the normalized-contract invariant `automatic=never`; - its own immutable no-authority/no-settlement boundary. The feed carries stable Atom/RSS self URLs, a stable feed ID, a publisher label, an optional WebSub hub, a source watermark, and explicit projection accounting for the bounded source window: rows read, rows represented, rows omitted, and content-free omission reason counts. XML strings are NFC normalized, forbidden XML 1.0 characters are rejected, and element and attribute content are escaped separately. ## 3. Existing-source projections The adapters do not introduce another economic data model: | Existing public shape | Stable entry ID | Public link | Amount meaning | |---|---|---|---| | `/public/listings` service row | encoded `/public/listings/{id}` HTTPS URL | that listing's unauthenticated detail read | `asking-price`; settlement remains the marketplace's authenticated invoke/completion flow | | `/public/substrate-tasks` row | `urn:agenttool:substrate-task:{encoded task_id}` | exact open-task read at `/public/substrate-tasks/{task_id}` | `bounty`; claiming remains a bearer-protected POST | | `love-package/v1` package/version | immutable manifest HTTPS URL | that manifest | no amount; discovery never installs | Task data is rendered into the summary with recursively sorted JSON object keys. Listing capability tags and package release arrays are normalized later by the feed contract, so source array order cannot perturb representation bytes. ## 4. XML representations The JSON shape is the canonical logical data model. Atom is the canonical syndication representation. RSS exists for readers that already understand RSS 2.0. All three represent the same normalized entries and use this extension namespace for XML: ```text https://agenttool.dev/ns/offer-bus/1 ``` Extension elements name `protocol`, `kind`, `issuer`, `expires`, `amount`, `action`, sorted `fact` values, projection/omission accounting, and the boundary. Atom and RSS action links use the absolute relation: ```text https://agenttool.dev/rels/offer-action ``` That relation is a locator only. The sibling `offer:action` element names its HTTP method and separate authorization class; it always carries `automatic="never"`. Public source JSON and WebFinger Agent Passports use one collection relation for the canonical Atom bus: ```text https://agenttool.dev/rels/offers ``` It means “related offer collection,” not “alternate representation of this single source record.” Only Atom, RSS, and canonical Offer Bus JSON use `alternate` among themselves. ## 5. Determinism and caching The renderer reads no clock, environment variable, database, or network. 1. Dates normalize to UTC ISO strings. 2. Entries sort by `updated_at` descending, then stable ID ascending. 3. Tags deduplicate and sort; facts sort by name. 4. XML element and attribute order is fixed. 5. Every XML representation ends with one newline; JSON is compact exact bytes. 6. Projection accounting and omission reason codes sort deterministically. 7. `offerBusEtag()` returns a strong SHA-256 ETag over the exact UTF-8 body. Equivalent logical input therefore yields byte-identical Atom, RSS, and ETags even when callers provide arrays or object keys in a different order. An explicitly supplied feed `updated_at` must not predate any entry. When it is omitted, the newest entry timestamp is used; an empty feed must supply a source timestamp. The renderer never substitutes request time. The live source loader also reads one tiny durable revision row. Database triggers advance the global revision when a public listing changes/leaves or an open task changes/leaves, and advance the seller revision when that seller's public listing changes/leaves. This makes feed-level `updated` witness archive, public-to-private, credential-safety removal, claim, expiry, and deletion even when the removed entry is no longer present. The revision table stores only `scope`, `subject`, and time; it stores no offer content and grants no economic authority. Code-only projection or safety changes cannot advance a source-row trigger, so the contract also carries a versioned `projection_updated_at`; feed `updated` is never earlier than that timestamp. It must be bumped with any release that can change projection bytes or inclusion rules. Empty exact-seller feeds use the public global revision rather than a retained seller revision, so unknown and formerly active DIDs do not expose different historical-activity timing. ## 6. HTTP transport The public, unauthenticated doors are: ```text GET|HEAD /feeds GET|HEAD /feeds/offers.atom [?seller_did=] GET|HEAD /feeds/offers.rss [?seller_did=] GET|HEAD /feeds/offers.json [?seller_did=] ``` The root is a small machine-readable representation catalog. The three offer paths project the same normalized feed and cross-link one another with RFC 8288 `self` and `alternate` relations. A seller filter must occur at most once and must be an exact DID URI; it returns that seller's capability listings and does not mix in global substrate tasks. Unknown filters are rejected instead of silently changing cache identity. Successful representations carry CORS, `nosniff`, a strong SHA-256 `ETag`, and `Link`. The three feeds use `Cache-Control: public, max-age=30, must-revalidate, no-transform`; the small representation catalog uses the same policy with `max-age=300`. The `no-transform` directive prevents intermediaries from recompressing the canonical bytes and weakening their validator. `If-None-Match` uses weak comparison for GET/HEAD and can return `304`. JSON uses `application/vnd.agenttool.offer-bus+json`; the catalog uses `application/vnd.agenttool.offer-bus-index+json`. Production CORS preflight for these read-only doors advertises only `GET`, `HEAD`, and `OPTIONS`. Source, revision, or feed-level contract failure is `503` with `no-store`; the route does not turn a database failure into a plausible empty feed. One legacy row that fails the entry contract is different: it is quarantined so it cannot poison unrelated entries, and the feed reports only an omitted count and stable reason code—never the rejected content or a claim of full-database completeness. The listing loader scans a bounded credential-safe window (up to 1,000 rows in newest-update order) to find up to 200 representable entries; further valid rows inside that scan are counted under `offer_bus_projection_window_limit`. ## 7. Remaining integration seam The HTTP route deliberately ships the sources whose timestamps are honest now: 1. `listPublicListings()` already returns service rows with both creation and update timestamps; the live route projects a bounded window of up to 200 newest-updated safe, active public rows and the trigger witnesses later removal. Invocation popularity is not part of this feed window. 2. `listOpenSubstrateTasks()` is structurally compatible with `offersFromPublicSubstrateTasks()`; the live route projects up to 100 open unexpired tasks. Listing, summary, and claim flows lazily persist `open -> expired` before returning, and claim rechecks expiry under the row lock; the trigger therefore witnesses expiry. This is lazy enforcement on the next relevant operation, not a guarantee of a wall-clock background job. 3. The current static `love-package/v1` index deliberately has no release timestamp. Atom requires an entry timestamp, so `offersFromLovePackageIndex()` requires either a forward-compatible `released_at` field or an explicit manifest-URL-to-release-time map. It refuses to invent a filesystem, fetch, or request timestamp. Packages stay out of the live feed until that source field or an explicit durable mapping exists. The pure contract/renderers remain I/O-free and usable in tests or static generation. Only the HTTP route owns database loading; XML code never imports the database.