Skip to content

Conversation

phbnf
Copy link
Contributor

@phbnf phbnf commented Aug 12, 2025

Personalities that need to wait should wait for a checkpoint to be published, rather than simple integration. For ease of writing, I think that it's okay to consider that "entries are published" only and only when "checkpoint covering these entries" has been published (even if the entries will be made public before then).

@phbnf phbnf requested a review from AlCutter August 12, 2025 14:42
@phbnf phbnf requested a review from a team as a code owner August 12, 2025 14:42
@phbnf phbnf added the documentation Improvements or additions to documentation label Aug 12, 2025
Copy link
Collaborator

@AlCutter AlCutter left a comment

Choose a reason for hiding this comment

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

This is kinda covered up in the #Publishing section:

An entry is considered published once it is committed to by a published Checkpoint (i.e. a published Checkpoint's size is larger than the entry's assigned index).

But it's not a bad idea to stress the point again here.

I've suggested a small tweak in wording to bring it closer into line with publication being mainly about checkpoints to avoid the potential for any misinterpretation/confusion about static resources appearing before a checkpoint has been successfully published. Have a look and see what you think.

Comment on lines +270 to +275
As discussed above in [Integration](#integration) and [Publishing](#publishing),
sequenced entries will be first _asynchronously_ integrated into the log, and
then published on the read API by a second _asynchronous_ process. Some
personalities may need to block until this has been performed, e.g. because they
will provide the requester with an inclusion proof, which requires integration
and publication. Such personalities are recommended to use [Synchronous Publication](#synchronous-publication)
Copy link
Collaborator

Choose a reason for hiding this comment

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

Suggested change
As discussed above in [Integration](#integration) and [Publishing](#publishing),
sequenced entries will be first _asynchronously_ integrated into the log, and
then published on the read API by a second _asynchronous_ process. Some
personalities may need to block until this has been performed, e.g. because they
will provide the requester with an inclusion proof, which requires integration
and publication. Such personalities are recommended to use [Synchronous Publication](#synchronous-publication)
As discussed above in [Integration](#integration) and [Publishing](#publishing),
sequenced entries will be _asynchronously_ integrated into the log, with a new `checkpoint` committing to these entries being published periodically by another asynchronous process.
Some personalities may need to block until this has been performed, e.g. because they will provide the requester with an inclusion proof, which requires both then integration of the entry and the publication of a new checkpoint to have completed. Such personalities are recommended to use [Synchronous Publication](#synchronous-publication)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Nice! More than stressing it out a second time, I think that the current phrasing is misleading: it suggests to wait for entries to be integrated and available, but that's not enough, one should really wait for a checkpoint to be published.

I like your wording better. I think that re-explaining the whole wheel every time is a bit cumbersome though. It makes sense here because we need to leave no room for confusion. I think that the concept of "publishing an entry" is relatively new, and I had not realized that it was already used in the Publishing section. If my understanding is correct, we use to refer to it as "integration", which included the "publication" part, but they have now been split in two.

Should we start using "entry publication" more broadly as part of the append lifecycle? Would there be a better word than "publishing" to avoid confusion with the fact that entries are already publicly available before being published? "entries commitment/entries are committed to"? I'm interested for the context of this PR, but also in general when speaking about log.

Suggested change
As discussed above in [Integration](#integration) and [Publishing](#publishing),
sequenced entries will be first _asynchronously_ integrated into the log, and
then published on the read API by a second _asynchronous_ process. Some
personalities may need to block until this has been performed, e.g. because they
will provide the requester with an inclusion proof, which requires integration
and publication. Such personalities are recommended to use [Synchronous Publication](#synchronous-publication)
As discussed above in [Integration](#integration) and [Publishing](#publishing),
sequenced entries will be {published/committed to} _asynchronously_: they will be integrated into the log, and a new `checkpoint` committing to these entries will be published on a clock by another asynchronous process.
Some personalities may need to block until this has been performed, e.g. because they will provide the requester with an inclusion proof, which requires both then integration of the entry and the publication of a new checkpoint to have completed. Such personalities are recommended to use [Synchronous Publication](#synchronous-publication)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
Status: No status
Development

Successfully merging this pull request may close these issues.

2 participants