docs(spec): separate host emit keys from the wire model - #153
Merged
Merged
Conversation
miravoss26
reviewed
Oct 3, 2026
miravoss26
left a comment
There was a problem hiding this comment.
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-modelsdoesn'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
force-pushed
the
docs/emit-keys-data-models
branch
from
October 4, 2026 16:16
ae9dbee to
f688686
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
invertersupport 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
make check: 4808 passed, 923 skipped.