fix: correct all incorrect info about warrants, validation (receipts),

authorities, etc

Author: pdaoust

.cspell/words-that-should-exist.txt

@@ -32,6 +32,7 @@ sandboxing
 scaffolder
 snapshotted
 spacebar
+Sybils
 todo
 todos
 unforgeable

src/assets/img/concepts/7.17-block-and-return-warrant.png

@@ -7,7 +7,7 @@ An agent receives **DHT operations**, which are requests for them to transform [
 :::
 
 !!! info Validating actions instead of DHT operations
-**This is an advanced topic.** Writing validation rules that checks DHT operations requires understanding Holochain's data model. Until you have a reason to write validation rules at this level of granularity, we recommend letting the [scaffolding tool](/get-started/3-forum-app-tutorial/) generate a `validate` callback for you, which calls out to [stub functions](/build/validate-callback/#create-boilerplate-code-with-the-scaffolding-tool) that validate the _actions_ that create, update, or delete your application's entry and link types, and makes opinionated but sensible choices about which groups of authorities should validate what portions of the op data. The following information is presented for people who have a specific need to further reduce overall validation overhead across the network.
+**This is an advanced topic.** Writing validation rules that check DHT operations requires understanding Holochain's data model. Until you have a reason to write validation rules at this level of granularity, we recommend letting the [scaffolding tool](/get-started/3-forum-app-tutorial/) generate a `validate` callback for you, which calls out to [stub functions](/build/validate-callback/#create-boilerplate-code-with-the-scaffolding-tool) that validate the _actions_ that create, update, or delete your application's entry and link types, and makes opinionated but sensible choices about which groups of authorities should validate what portions of the op data. The following information is presented for people who have a specific need to further reduce overall validation overhead across the network.
 !!!
 
 ## What is a DHT operation?
@@ -38,7 +38,7 @@ While the following info describes the way Holochain should work [as formally sp
     * [`RegisterAgentActivity`](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/op/enum.Op.html#variant.RegisterAgentActivity) {#register-agent-activity}
         * Basis address: author's public key
         * Contents: action
-        * System validation: Check for non-monotonic sequence indices and timestamps in adjacent actions, and detect [source chain forks](/resources/glossary/#fork-source-chain).
+        * System validation: Check for non-monotonic sequence indices and timestamps in the chain of actions, and detect [source chain forks](/resources/glossary/#fork-source-chain).
         * Effect: Append the action to a replica of the author's source chain.
     * [`StoreRecord`](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/op/enum.Op.html#variant.StoreRecord) {#store-record}
         * Basis address: action hash
@@ -55,7 +55,7 @@ While the following info describes the way Holochain should work [as formally sp
     * [`RegisterUpdate`](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/op/enum.Op.html#variant.RegisterUpdate)
         * Basis addresses: entry and action hashes of the _old_ entry being updated
         * Contents: action and entry <!--TODO: system validation? -->
-        * Effect: Mark an entry creation action as being replaced by a new one, pointing the the entry and action that replace it. **An entry and its creation action can have multiple actions updating them.**
+        * Effect: Mark an entry creation action as being replaced by a new one, pointing to the entry and action that replace it. **An entry and its creation action can have multiple actions updating them.**
 * [`Delete`](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/action/enum.Action.html#variant.Delete)
     * [`RegisterDelete`](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/op/enum.Op.html#variant.RegisterDelete)
         * Basis addresses: entry and action hashes of the entry being deleted

src/assets/img/concepts/7.17-gossip-warrant.png

@@ -339,9 +339,9 @@ You can use any of these identifiers as a field in your entry types to model a m
 
 ### As a single record
 
-Get a record by calling [`hdk::entry::get`](https://docs.rs/hdk/latest/hdk/entry/fn.get.html) with the hash of either its entry creation action. The return value is an <code>Option&lt;[holochain_integrity_types::record::Record](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/record/struct.Record.html)&gt;</code> wrapped in an `ExternResult`.
+Get an entry as a record by calling [`hdk::entry::get`](https://docs.rs/hdk/latest/hdk/entry/fn.get.html) with the hash of the entry creation action. The return value is an <code>Option&lt;[holochain_integrity_types::record::Record](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/record/struct.Record.html)&gt;</code> wrapped in an `ExternResult`. If the record is invalid or missing, the option will be `None`.
 
-You can also pass an _entry hash_ to `get`, and the record returned will contain the _oldest live_ entry creation action that wrote it.
+You can also pass an _entry hash_ to `get`, and the record returned will contain the _oldest-timestamped, valid, live_ entry creation action that wrote it.
 
 ```rust
 use hdk::prelude::*;
@@ -387,7 +387,11 @@ match maybe_record {
 
 #### Records
 
-To get a record and all the updates, deletes, and outbound links associated with its action, as well as its current validation status, call [`hdk::entry::get_details`](https://docs.rs/hdk/latest/hdk/entry/fn.get_details.html) with an _action hash_. You'll receive an <code>Option&lt;[holochain_zome_types::metadata::Details::Record](https://docs.rs/holochain_zome_types/latest/holochain_zome_types/metadata/enum.Details.html)&gt;</code> wrapped in an `ExternResult`; this enum variant contains a [`RecordDetails`](https://docs.rs/holochain_zome_types/latest/holochain_zome_types/metadata/struct.RecordDetails.html).
+To get a record and all the updates and deletes associated with its action, as well as its current validation status, call [`hdk::entry::get_details`](https://docs.rs/hdk/latest/hdk/entry/fn.get_details.html) with an _action hash_. You'll receive an <code>Option&lt;[holochain_zome_types::metadata::Details::Record](https://docs.rs/holochain_zome_types/latest/holochain_zome_types/metadata/enum.Details.html)&gt;</code> wrapped in an `ExternResult`; this enum variant contains a [`RecordDetails`](https://docs.rs/holochain_zome_types/latest/holochain_zome_types/metadata/struct.RecordDetails.html).
+
+!!! info Invalid data or metadata
+The record will be returned even if it's invalid; check the `validation_status` field. Only valid updates and deletes will be returned.
+!!!
 
 ```rust
 use hdk::prelude::*;
@@ -418,7 +422,11 @@ match maybe_details {
 
 #### Entries
 
-To get an entry and all the deletes and updates that operated on it (or rather, that operated on the entry creation actions that produced it), _as well as_ all its entry creation actions and its current status on the DHT, pass an _entry hash_ to [`hdk::entry::get_details`](https://docs.rs/hdk/latest/hdk/entry/fn.get_details.html). You'll receive an <code>Option&lt;[`holochain_zome_types::metadata::Details::Entry`](https://docs.rs/holochain_zome_types/latest/holochain_zome_types/metadata/enum.Details.html)&gt;</code> wrapped in an `ExternResult`; this enum variant contains an [`EntryDetails`](https://docs.rs/holochain_zome_types/latest/holochain_zome_types/metadata/struct.EntryDetails.html).
+To get an entry and all of its creation actions (both creates and updates), as well as all the valid deletes and updates that operated on it (or rather, that operated on the entry creation actions that produced it), pass an _entry hash_ to [`hdk::entry::get_details`](https://docs.rs/hdk/latest/hdk/entry/fn.get_details.html). You'll receive an <code>Option&lt;[`holochain_zome_types::metadata::Details::Entry`](https://docs.rs/holochain_zome_types/latest/holochain_zome_types/metadata/enum.Details.html)&gt;</code> wrapped in an `ExternResult`; this enum variant contains an [`EntryDetails`](https://docs.rs/holochain_zome_types/latest/holochain_zome_types/metadata/struct.EntryDetails.html).
+
+!!! info Invalid data or metadata
+The entry will be returned even if all of its creation actions are invalid; check the [`actions`](https://docs.rs/holochain_zome_types/latest/holochain_zome_types/metadata/struct.EntryDetails.html#structfield.actions) field for valid creation actions and [`rejected_actions`](https://docs.rs/holochain_zome_types/latest/holochain_zome_types/metadata/struct.EntryDetails.html#structfield.rejected_actions) for invalid ones. Only valid deletes and updates will be returned. Note that currently [`entry_dht_status`](https://docs.rs/holochain_zome_types/latest/holochain_zome_types/metadata/struct.EntryDetails.html#structfield.entry_dht_status) is only `Live` or `Dead`, which only takes valid creation and deletion actions into account. All other entry DHT status variants are unused.
+!!!
 
 ```rust
 use hdk::prelude::*;

src/assets/img/concepts/7.18-publish-warrants.png

@@ -28,16 +28,16 @@ The four-byte DHT location is calculated from the 32 bytes of the hash and is us
 
 There are also a couple of composite types, [`AnyDhtHash`](https://docs.rs/holo_hash/latest/holo_hash/type.AnyDhtHash.html) and [`AnyLinkableHash`](https://docs.rs/holo_hash/latest/holo_hash/type.AnyLinkableHash.html).
 
-Here's an overview of the five types above, plus two composite types:
+Here's an overview of the five types above, plus the two composite types:
 
-* `DnaHash` is the hash of the DNA bundle (including any DNA modifiers passed in at installation or cloning time), and is the [unique identifier for the network](/build/working-with-data/#storage-locations-and-privacy).
+* `DnaHash` is the hash of the DNA bundle (including any DNA modifiers passed in at installation or cloning time), and is the [unique identifier for the DNA's network](/build/working-with-data/#storage-locations-and-privacy).
 * `AgentPubKey` is the public key of a participant in a network.
 * `ActionHash` is the hash of a structure called an [action](/build/working-with-data/#entries-actions-and-records-primary-data) that records a participant's act of storing or changing private or shared data.
 * `EntryHash` is the hash of an arbitrary blob of bytes called an [entry](/build/entries/), which contains application or system data. (Note: there's a special system entry called [`Agent`](https://docs.rs/holochain_zome_types/latest/holochain_zome_types/enum.Entry.html#variant.Agent), which holds the agent's public key; the hash function returns the public key itself, _not_ its hash.)
 * `ExternalHash` is the ID of a resource that exists outside the database, such as the hash of an IPFS resource or the public key of an Ethereum wallet. Holochain doesn't care about its value, as long as it's 32 bytes long. There's no content stored at the address; it simply serves as an anchor to attach [links](/build/links-paths-and-anchors/) to.
 * Composite types --- if one of the types above is eligible, it can be converted into one of these two types via the `.into()` method. Functions that take the below types will implicitly convert from the above types.
     * `AnyDhtHash` is the hash of any kind of addressable content (actions, entries, and agent public keys). Any
-    * `AnyLinkableHash` is the hash of anything that can be linked to or from (that is, all of the above).
+    * `AnyLinkableHash` is the hash of anything that can be linked to or from (that is, all of the above, or `AnyDhtHash` + `ExternalHash`).
 
 ## Getting hashes
 
@@ -86,7 +86,7 @@ if let Action::Update(action_data) = action {
 
 ### Entry
 
-To get the hash of an entry, first construct an instance of the entry type that you [defined in the integrity zome](/build/entries/#define-an-entry-type), then pass it through the [`hdk::hash::hash_entry`](https://docs.rs/hdk/latest/hdk/hash/fn.hash_entry.html) function. (You don't actually have to write the entry to a source chain to get the entry hash.)
+To get the hash of an entry, first construct an instance of the entry type that you [defined in the integrity zome](/build/entries/#define-an-entry-type), then pass it through the [`hdk::hash::hash_entry`](https://docs.rs/hdk/latest/hdk/hash/fn.hash_entry.html) function. (You don't actually have to write the entry to a source chain to get its hash.)
 
 ```rust
 use hdk::hash::*;
@@ -189,7 +189,7 @@ let ipfs_movie_poster_hash = ExternalHash::from_raw_32(vec![/* bytes of external
 
 ### DNA
 
-There is one global hash that everyone knows, and that's the hash of the DNA itself. You can get it by calling [`hdk::info::dna_info`](https://docs.rs/hdk/latest/hdk/info/fn.dna_info.html).
+In every application, there is one global hash that everyone knows, and that's the hash of the DNA itself. You can get it by calling [`hdk::info::dna_info`](https://docs.rs/hdk/latest/hdk/info/fn.dna_info.html).
 
 ```rust
 use hdk::prelude::*;
@@ -201,7 +201,7 @@ let dna_hash = dna_info()?.hash;
 
 ### In DHT data
 
-To reference an address in your entry data, define a field in your entry that can hold the right kind of address. The HDK will take care of serialization and deserialization for you. The following entry types have fields that reference other DHT data.
+To reference an address in your entry data, define a field in your entry type that can hold the right kind of address. The HDK will take care of serialization and deserialization for you. The following entry types have fields that reference other DHT data.
 
 ```rust
 use hdi::prelude::*;

src/assets/img/concepts/7.18-ejection.png renamed to src/assets/img/concepts/7.19-ejection.png

@@ -100,7 +100,7 @@ let delete_link_action_hash = delete_link(
 );
 ```
 
-A link is considered ["dead"](/build/working-with-data/#deleted-dead-data) (deleted but retrievable if asked for explicitly) once its creation action has at least one delete-link action associated with it. As with entries, dead links can still be retrieved with [`hdk::entry::get_details`](https://docs.rs/hdk/latest/hdk/entry/fn.get_details.html) or [`hdk::link::get_link_details`](https://docs.rs/hdk/latest/hdk/link/fn.get_link_details.html) (see next section).
+A link is live as long as its creation action is valid and there are no valid delete-link actions associated with it. Otherwise, it's considered ["dead"](/build/working-with-data/#deleted-dead-data). As with entries, dead links can still be retrieved with [`hdk::link::get_link_details`](https://docs.rs/hdk/latest/hdk/link/fn.get_link_details.html) (see next section).
 
 ### Deleting a link, under the hood
 
@@ -119,7 +119,7 @@ At this point, the action hasn't been persisted to the source chain. Read the [z
 
 ## Retrieve links
 
-Get all the _live_ (undeleted) links attached to a hash with the [`hdk::link::get_links`](https://docs.rs/hdk/latest/hdk/link/fn.get_links.html) function. The input is complicated, so use [`hdk::link::builder::GetLinksInputBuilder`](https://docs.rs/hdk/latest/hdk/link/builder/struct.GetLinksInputBuilder.html) to build it.
+Get all the live links attached to a hash with the [`hdk::link::get_links`](https://docs.rs/hdk/latest/hdk/link/fn.get_links.html) function. The input is complicated, so use [`hdk::link::builder::GetLinksInputBuilder`](https://docs.rs/hdk/latest/hdk/link/builder/struct.GetLinksInputBuilder.html) to build it.
 
 ```rust
 use hdk::prelude::*;
@@ -148,7 +148,7 @@ let movies_in_1960s_by_director = get_links(
 )?;
 ```
 
-To get all live _and deleted_ links, along with any deletion actions, use [`hdk::link::get_link_details`](https://docs.rs/hdk/latest/hdk/link/fn.get_link_details.html).
+To get all live _and deleted_ links (where ), along with any deletion actions, use [`hdk::link::get_link_details`](https://docs.rs/hdk/latest/hdk/link/fn.get_link_details.html).
 
 ```rust
 use hdk::prelude::*;
@@ -162,6 +162,10 @@ let movies_plus_deleted = get_link_details(
 )?;
 ```
 
+!!! info Invalid links
+There is no way to retrieve invalid link creation or deletion actions from a base.
+!!!
+
 ### Count links
 
 If all you need is a _count_ of matching links, use [`hdk::link::count_links`](https://docs.rs/hdk/latest/hdk/link/fn.count_links.html). It has a different input with more options for querying (we'll likely update the inputs of `get_links` and `count_links` to match in the future).
@@ -185,7 +189,7 @@ let number_of_reviews_written_by_me_in_last_month = count_links(
 ```
 
 !!! info Links are counted locally
-Currently `count_links` retrieves all link hashes from the remote peer, then counts them locally. So it is less network traffic than a `get_links` request, but more network traffic than just sending an integer.
+Currently `count_links` retrieves all links from the remote peer, then counts them locally. As with `get_links`, only live links are included.
 !!!
 
 ## Anchors and paths

src/pages/build/dht-operations.md

@@ -171,7 +171,7 @@ fn check_that_action_exists_and_is_valid_and_has_valid_public_app_entry(action_h
 !!! info This may not catch all validation failures
 `must_get_valid_record` checks for validation success or failure on the [`StoreRecord` DHT operation](/build/dht-operations/#store-record). Validation code for other DHT operations produced from the same action may have executed and failed.
 
-In the future, we intend to introduce 'warrants', a feature which will allow validators to communicate failures to each other for related data. Until then, if any of your validation code uses `must_get_valid_record` to retrieve a dependency, we recommend that the dependency's validation code for the `StoreRecord` operation cover all possible checks.
+[**Warrants**](/resources/glossary/#warrant) allow a validator to communicate news of an invalid DHT operation to non-authorities. But because they're not guaranteed to be co-located with the failed op, or even guaranteed to be delivered at all, they can't be used in a validation callback, which must work with a closed, deterministic set of data. If you absolutely need `must_get_valid_record` to fail for _all_ possible validity issues for a dependency, make sure the dependency's validation code for the `StoreRecord` operation covers all possible checks.
 !!!
 
 ## Reference