Check what a producer publishes

For

Developers of a system that publishes HOS facts: PMS, housekeeping, messaging

Time

20 minutes

You need

hos, see Install

Status

Draft

Why this matters#

A consumer is tested with made-up scenarios. A producer is judged on what it publishes, because every consumer relies on it. If its facts are not declared in its manifest, consumers ignore them. If, after a restart, it publishes the same reservation under a new id, every consumer takes it for a new fact: a stay counted twice, a room status that jumps back. The producer checks catch both before a hotel does.

The four checks#

1. The manifest is valid, and states its limitations: what the system does not do, does not know, or cannot share.
2. Every recorded fact is valid, published under the manifest's producer, and declared for the hotel it concerns.
3. No source and id name two different facts.
4. A redelivery gives the same facts back: published again from the same data, for example after a restart, every fact comes back with the same id and the same content.

1. Check an example producer

   HOS publishes the files of an example PMS: its manifest, five facts it published, and what it published again after a restart. Download them into a new folder:

   PowerShellCommand PromptmacOS / Linux

   curl -O https://hos-ai.vercel.app/docs/tools/examples/producer/manifest.json
   curl -O https://hos-ai.vercel.app/docs/tools/examples/producer/recording.jsonl
   curl -O https://hos-ai.vercel.app/docs/tools/examples/producer/redelivery.jsonl

   Terminal

   npx @hos-ai/cli conformance producer --manifest manifest.json --stream recording.jsonl --redelivery redelivery.jsonl

   $ npx @hos-ai/cli conformance producer --manifest manifest.json --stream recording.jsonl --redelivery redelivery.jsonl
   Producer urn:hos:pms:demo
   ✓ manifest.json: valid manifest, with its limitations
   ✓ recording.jsonl: 5 facts, valid and declared
   ✓ redelivery.jsonl: 5 facts, each already in the recording with the same id and content
   
   ✓ urn:hos:pms:demo passes the producer checks.

   What just happened. hos read the manifest of urn:hos:pms:demo and checked it. It checked each of the five recorded facts against the HOS schemas and against the manifest. Then it compared the redelivery with the recording: the same five facts, with the same ids and content. A consumer that receives them again discards them as duplicates.

2. Restart with new ids

   A common mistake: the adapter gives each fact a new id when it publishes it, for example a random one or a counter. After a restart, the same reservation comes back under another id.

   Open redelivery.jsonl, replace pms-000312 with pms-000999, save, and run the check again:

   Output

   Producer urn:hos:pms:demo
   ✓ manifest.json: valid manifest, with its limitations
   ✓ recording.jsonl: 5 facts, valid and declared
   ✗ redelivery.jsonl: 5 facts, 4 already in the recording unchanged (1 error)
     error   line 1: pms-000999 from urn:hos:pms:demo is not in the recording. Publishing the same data again, a producer publishes the same facts with the same ids, so consumers discard them as duplicates.
             rule events/at-least-once-delivery · at /id
   
   ✗ urn:hos:pms:demo fails the producer checks.

   Every consumer would take this fact for a new reservation. Put pms-000312 back.

3. Restart with changed content

   Another mistake: the adapter fills a field from its own clock rather than from the source data. After a restart, the same fact comes back with another value.

   In redelivery.jsonl, replace 2026-07-12T14:03:00Z, the time the reservation was made, with 2026-07-30T12:00:00Z, and run the check again:

   Output

   Producer urn:hos:pms:demo
   ✓ manifest.json: valid manifest, with its limitations
   ✓ recording.jsonl: 5 facts, valid and declared
   ✗ redelivery.jsonl: 5 facts, 4 already in the recording unchanged (1 error)
     error   line 1: pms-000312 comes back with different content (time). A source and id name one fact, which never changes: a correction is a new event.
             rule events/immutable-facts
   
   ✗ urn:hos:pms:demo fails the producer checks.

   A fact never changes once published. A consumer that has the first version discards the second as a duplicate, and never sees the difference. Put the time back.

Check your own producer#

You need the same three files from your system.

• manifest.json: your producer's manifest. Sign and publish a producer manifest explains how to publish it.
• recording.jsonl: every fact your adapter publishes during a test, one JSON object per line, in the order it published them. The simplest way is to have the adapter append each fact it publishes to a file, one line each. Record one producer per file.
• redelivery.jsonl, the redelivery: stop the adapter, start it again with the state it keeps between runs, such as its identity crosswalk, feed it the same source data, and record what it publishes. A producer that remembers what it already published may publish nothing again: an empty redelivery passes.

The HOS mappings of Mews, Apaleo and Cloudbeds are checked this way, from their read-only live checks: lib/hos/mappings/sync.ts delivers the same data twice, then through a restarted adapter, and runs the same check.

--redelivery is optional. Without it, hos checks the manifest and the recording:

npx @hos-ai/cli conformance producer --manifest manifest.json --stream recording.jsonl

Producer urn:hos:pms:demo
✓ manifest.json: valid manifest, with its limitations
✓ recording.jsonl: 5 facts, valid and declared

✓ urn:hos:pms:demo passes the producer checks.

Same data, same facts#

To pass the fourth check, derive every part of a fact from the source data, never from the moment you publish it:

• the id, from the source's own key for the event, the HOS type and the source's time for it. The same source event then always gets the same id, whatever the process that publishes it.
• the content, from what the source says: its times, its statuses, its references.
• the HOS ids of entities, such as stay_1042 or unit_204, from a crosswalk your adapter keeps between runs, so that a restart finds the same ones.

hosrecordedat, the time your system recorded the fact, is the exception: hos leaves it out of the comparison, as a producer may record the same fact again.

Get the result as JSON#

npx @hos-ai/cli conformance producer --manifest manifest.json --stream recording.jsonl --redelivery redelivery.jsonl --json

{
  "valid": true,
  "producer": "urn:hos:pms:demo",
  "manifest": {
    "valid": true,
    "errors": []
  },
  "recording": {
    "valid": true,
    "events": 5,
    "issues": []
  },
  "redelivery": {
    "valid": true,
    "events": 5,
    "issues": [],
    "repeated": 5
  }
}

repeated counts the facts of the redelivery already in the recording, with the same id and content.

Next steps#

• Sign and publish a producer manifest: let consumers check who declared what.
• Validate events, manifests and streams: the checks behind the recording line.
• Run the checks in CI: run the producer check on every change of your adapter.