vexa_stations.py

usage: vexa-stations [-h] [--ledger LEDGER] {record-publish,record-ingest,pin,show} ...

vexa-stations — the reducer that writes the channel/station ledger.

The bucket behind `channel.vexa.ai` is a DISTRIBUTION copy. This module writes
the thing it is a copy of: a git repository (a private repository) that
holds, per channel, what has been published and where every station stands.

    channels/<channel>/channel.yaml                 last entry_seq, current
                                                    position, pin map, expiry
    channels/<channel>/stations/<station>/state.yaml   subscribed position,
                                                    last receipt, flags
    channels/<channel>/stations/<station>/receipts/     ingested bundles verbatim

**Git history IS the audit trail.** Every reducer call is one commit, made BY
PATHSPEC, naming what moved. There is no separate log to keep in sync, and
nothing here is a cache of the bucket: after this, `entry_seq` authority lives
in `channel.yaml` and the copy inside the published entry is derived.

**One writer per surface**, which is the whole design and the only rule that
matters when two operators run at once:

  - `vexa_channel.py push`  is the sole writer of `channel.yaml`
  - `vexa_station.py ingest` is the sole writer of `stations/<station>/*`

A surface with two writers does not error. It produces a plausible result and
loses one writer's intent, which is why the split is enforced here rather than
left to convention: `record_publish` refuses to touch a station directory and
`record_ingest` refuses to touch `channel.yaml`.

The one fact that legitimately appears on both sides is a station's position,
and it appears as TWO DIFFERENT FACTS. `channel.yaml`'s `pins:` is the
publisher's intent — what we promoted this station to, moved by a human's pin
commit. `state.yaml`'s `subscribed_position` is the observation — what the
station's own bundle said it was following when it last reported. A divergence
between them is a finding, not a bug: it means a promotion did not land, or a
station moved itself.

positional arguments:
  {record-publish,record-ingest,pin,show}
    record-publish      reduce a published entry into channel.yaml
    record-ingest       reduce an ingested station into state.yaml
    pin                 move a station's pin (a promotion)
    show                render the ledger

options:
  -h, --help            show this help message and exit
  --ledger LEDGER       checkout of the vexa-stations ledger (default: $VEXA_STATIONS_DIR)

usage: vexa-stations record-publish [-h] --entry ENTRY [--entry-digest ENTRY_DIGEST] [--ref REF]
                                    [--channel-tag CHANNEL_TAG] [--note NOTE]

options:
  -h, --help            show this help message and exit
  --entry ENTRY         built entry directory or entry.json
  --entry-digest ENTRY_DIGEST
                        digest the entry was pushed at
  --ref REF             registry ref the entry lives at
  --channel-tag CHANNEL_TAG
                        moving tag (default current)
  --note NOTE           one line about why this entry exists

usage: vexa-stations record-ingest [-h] --channel CHANNEL --station STATION
                                   --station-dir STATION_DIR [--bundle BUNDLE]

options:
  -h, --help            show this help message and exit
  --channel CHANNEL
  --station STATION
  --station-dir STATION_DIR
                        stations/<name>/ as written by vexa_station.py ingest
  --bundle BUNDLE       the station report, stored verbatim in receipts/

usage: vexa-stations pin [-h] --channel CHANNEL --station STATION --position POSITION
                         --justification JUSTIFICATION

options:
  -h, --help            show this help message and exit
  --channel CHANNEL
  --station STATION
  --position POSITION   chart version, or * to follow
  --justification JUSTIFICATION
                        the dev station's receipt that justifies the promotion

usage: vexa-stations show [-h]

options:
  -h, --help  show this help message and exit