Skip to content

docs(spec): separate host emit keys from the wire model - #153

Merged
frahlg merged 1 commit into
mainfrom
docs/emit-keys-data-models
Oct 4, 2026
Merged

frahlg merged 1 commit into
mainfrom
docs/emit-keys-data-models

Conversation

@davmoz

@davmoz davmoz commented Oct 1, 2026 •

Copy link
Copy Markdown
Member

Problem

The host API guide claimed that Lua emit keys matched Sourceful data-models verbatim. They are separate contracts: each host reads exact Lua keys and maps them to its wire model. Treating the proposed v3.0 wire names as current host keys would lose readings on hosts that do not accept them.

Change

Link to the published data-models field reference, explain the existing FTW and Blixt keys, and mark the v3.0 migration as proposed. inverter support is tied to srcfl/srcful-data-models#10 and srcfl/srcful-novacore#174, which remain open. The guide tells drivers to keep their target host's keys until host and ingest support lands.

This is a documentation change. It can land before those proposals because it describes their pending state rather than claiming that they shipped.

Validation

  • Confirmed that the published data-models reference describes v2.0.0 and both v3.0 prerequisites remain open.
  • Full make check: 4808 passed, 923 skipped.
  • No driver or manifest changed.

@miravoss26 miravoss26 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mira's review (pr-steward sweep).

Summary: spec-only change to spec/host-api.md. The emit key list moves to srcful-data-models, and it adds a DER-kind mapping table and rules: lowercase non-unit name parts, _ac/_dc postfixes, null rather than zero. The paragraph saying Blixt keeps its legacy keys until the host changes is useful.

Findings:

  • Medium: same link problem as srcful-documentation#31. srcfl/srcful-data-models doesn't resolve from my account. Please confirm it exists and is public before merge.
  • Low: "A value that was not read is not emitted (nil)" (host side) and "every field is present, unread is null" (wire side) are both right, but one sentence saying which layer each applies to would stop a driver author from mixing them up.
  • Low: the doc says NovaCore still accepts the pre-3.0 names "for now" with no date or tracking issue. Worth a follow-up.

Safe to merge from my read, once the link is confirmed. Comment only: this repo isn't on the steward's merge allowlist.

Link to the published data-models reference and mark the v3.0 migration as proposed. Keep the current host keys until host and ingest support lands.

Signed-off-by: Fredrik Ahlgren <fredrik@sourceful-labs.com>
@frahlg
frahlg force-pushed the docs/emit-keys-data-models branch from ae9dbee to f688686 Compare October 4, 2026 16:16
@frahlg frahlg changed the title docs(spec): point host.emit field names to srcful-data-models docs(spec): separate host emit keys from the wire model Oct 4, 2026
@frahlg
frahlg merged commit b696910 into main Oct 4, 2026
5 checks passed
@frahlg
frahlg deleted the docs/emit-keys-data-models branch October 4, 2026 16:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants