Chore: Sweep for incorrect/outdated information #607
Conversation
|
Warning Rate limit exceeded@pdaoust has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 13 minutes and 8 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (1)
WalkthroughDocumentation changes across Build, Concepts, and Resources introduce warrants into validation narratives, tighten liveliness semantics to require valid actions, clarify record vs entry retrieval and hashing guidance, expand glossary anchors/terms, fix wording/typos, and add spell-check words. No code or public API changes. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches❌ Failed checks (1 warning, 1 inconclusive)
✅ Passed checks (3 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
pdaoust
force-pushed
the
chore/warrants
branch
2 times, most recently
from
025d117 to
70b3673
Compare
pdaoust
force-pushed
the
chore/warrants
branch
from
70b3673 to
d0fcd4a
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (19)
.cspell/custom-words.txt (1)
52-52: Include base/related word forms for better coverage.Add “prevalidate”, “prevalidated”, “prevalidating”, and “prevalidation” to avoid future false positives.
.cspell/words-that-should-exist.txt (1)
35-35: Add singular as well.Include “Sybil” alongside “Sybils” to cover both forms.
src/pages/concepts/6_crud_actions.md (2)
76-76: Forward‑looking language is fine; ensure consistency with Key takeaways.Line 83 currently says “we intend to introduce”; prefer the same tentative tone (“may introduce”) to avoid over‑promising.
- In the future we intend to introduce actions that request the actual deletion of data. + In the future we may introduce actions that request the actual deletion of data.
76-76: Fix missing alt text flagged by markdownlint (MD045).Several images in this page use empty alt text; add brief descriptive alt attributes.
src/pages/build/identifiers.md (2)
31-41: Tighten AnyLinkableHash wording.Clarify it’s a union: “AnyLinkableHash = AnyDhtHash or ExternalHash,” rather than “AnyDhtHash + ExternalHash.”
204-205: Minor phrasing tweak.Consider “define a field in your entry type that holds the right address type” (slightly crisper).
src/pages/concepts/4_dht.md (2)
172-173: Fix subject–verb agreement.“…the authorities runs…” → “…the authorities run…”.
- After this first check, the authorities runs the data through + After this first check, the authorities run the data through
174-175: LGTM; consider cross‑linking “warrant.”Content matches the warrants model; add an inline link to the glossary/section on warrants.
src/pages/resources/glossary.md (3)
466-474: Fix invalid intra-page link fragments by pinning explicit IDs for “hApp bundle” and “hApp manifest”.markdownlint flagged broken fragments. Auto‑generated anchors for “hApp …” headers can differ (“happ‑bundle/manifest” vs “h-app‑bundle/manifest”). Pin explicit IDs to match existing links.
-#### hApp bundle +#### hApp bundle {#h-app-bundle} ... -#### hApp manifest +#### hApp manifest {#h-app-manifest}
948-951: Stabilize “Web hApp” anchors.For consistency with links using “#web-h-app”, add an explicit ID.
-#### Web hApp +#### Web hApp {#web-h-app}Also applies to: 127-129
259-270: Typo: “give a DNA DNA its API”.Remove redundant “[DNA]”.
-... Arbitrary public zome functions give a DNA [DNA](#dna) its API ... +... Arbitrary public zome functions give a DNA its API ...src/pages/build/must-get-host-functions.md (3)
17-19: Typo: duplicated “as”.-... use an action hash as as a dependency's identifier ... +... use an action hash as a dependency's identifier ...
70-79: Integrity callback macro should be hdi_extern, not hdk_extern.The validate callback lives in an integrity zome. Using hdk_extern can mislead readers.
-#[hdk_extern] +#[hdi_extern] pub fn validate(op: Op) -> ExternResult<ValidateCallbackResult> {
108-126: Time‑window logic likely inverted and order‑dependent.You compute a future bound (add 60s) and use take_while with “>=”, which probably yields zero results. Suggest subtracting 60s and filtering by “>= lower_bound”, ensuring iteration order is newest→oldest (or sort accordingly).
- let take_until_timestamp = action.timestamp().saturating_add(&Duration::new(60, 0)); + let lower_bound = action.timestamp().saturating_sub(&Duration::new(60, 0)); ... - .take_while(|a| a.timestamp() >= take_until_timestamp) + .take_while(|a| a.timestamp() >= lower_bound)If must_get_agent_activity isn’t guaranteed to return newest→oldest, sort the slice first.
src/pages/build/dht-operations.md (3)
41-47: Fix list indentation to satisfy MD007.Indent sub-bullets by 2–4 spaces consistently under the operation item.
- * System validation: Check for non-monotonic sequence indices and timestamps ... + * System validation: Check for non-monotonic sequence indices and timestamps ...
58-59: Same indentation issue here (MD007).Adjust sub-bullet indent under RegisterUpdate.
- * Effect: Mark an entry creation action as being replaced ... + * Effect: Mark an entry creation action as being replaced ...
70-73: Doc link points to wrong enum variant.DeleteLink’s op links to RegisterCreateLink; should be RegisterDeleteLink.
- * [`RegisterDeleteLink`](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/op/enum.Op.html#variant.RegisterCreateLink) + * [`RegisterDeleteLink`](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/op/enum.Op.html#variant.RegisterDeleteLink)src/pages/concepts/7_validation.md (2)
186-186: Add alt text to images (MD045).Accessibility: provide concise alt text for each diagram.
-{.sz80p} {.center} +{.sz80p} {.center}Apply similarly to other flagged images.
Also applies to: 226-226, 234-234, 242-242
313-314: Typo: duplicated “before”.-* Peers in the DHT subject all public data to validation before before storing. ... +* Peers in the DHT subject all public data to validation before storing. ...
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (4)
src/assets/img/concepts/7.17-block-and-return-warrant.pngis excluded by!**/*.pngsrc/assets/img/concepts/7.17-gossip-warrant.pngis excluded by!**/*.pngsrc/assets/img/concepts/7.18-publish-warrants.pngis excluded by!**/*.pngsrc/assets/img/concepts/7.19-ejection.pngis excluded by!**/*.png
📒 Files selected for processing (16)
.cspell/custom-words.txt(1 hunks).cspell/words-that-should-exist.txt(1 hunks)src/pages/build/dht-operations.md(3 hunks)src/pages/build/entries.md(3 hunks)src/pages/build/identifiers.md(4 hunks)src/pages/build/links-paths-and-anchors.md(5 hunks)src/pages/build/must-get-host-functions.md(1 hunks)src/pages/build/validation.md(1 hunks)src/pages/build/working-with-data.md(5 hunks)src/pages/concepts/10_countersigning.md(1 hunks)src/pages/concepts/2_application_architecture.md(2 hunks)src/pages/concepts/4_dht.md(2 hunks)src/pages/concepts/6_crud_actions.md(1 hunks)src/pages/concepts/7_validation.md(13 hunks)src/pages/resources/glossary.md(31 hunks)src/pages/resources/index.md(1 hunks)
🧰 Additional context used
🧠 Learnings (2)
📚 Learning: 2025-09-11T13:19:23.020Z
Learnt from: pdaoust
PR: holochain/docs-pages#597
File: src/pages/resources/glossary.md:933-939
Timestamp: 2025-09-11T13:19:23.020Z
Learning: In the holochain/docs-pages repository, pdaoust prefers glossary definitions to be "future-correct" rather than strictly reflecting current implementation status, to reduce maintenance burden when features are implemented.
Applied to files:
src/pages/resources/index.mdsrc/pages/resources/glossary.md
📚 Learning: 2025-08-28T23:39:06.675Z
Learnt from: pdaoust
PR: holochain/docs-pages#600
File: src/pages/get-started/install-advanced.md:74-81
Timestamp: 2025-08-28T23:39:06.675Z
Learning: hc-launch may show older Holochain version dependencies (like "holochain 0.5.3") even when other tools show newer versions (like 0.5.5) because hc-launch is only repackaged when necessary for compatibility, not automatically with every Holochain release.
Applied to files:
src/pages/resources/glossary.md
🪛 markdownlint-cli2 (0.17.2)
src/pages/concepts/6_crud_actions.md
77-77: Images should have alternate text (alt text)
(MD045, no-alt-text)
src/pages/build/dht-operations.md
41-41: Unordered list indentation
Expected: 4; Actual: 8
(MD007, ul-indent)
58-58: Unordered list indentation
Expected: 4; Actual: 8
(MD007, ul-indent)
src/pages/concepts/7_validation.md
186-186: Images should have alternate text (alt text)
(MD045, no-alt-text)
226-226: Images should have alternate text (alt text)
(MD045, no-alt-text)
234-234: Images should have alternate text (alt text)
(MD045, no-alt-text)
242-242: Images should have alternate text (alt text)
(MD045, no-alt-text)
src/pages/resources/glossary.md
468-468: Link fragments should be valid
(MD051, link-fragments)
468-468: Link fragments should be valid
(MD051, link-fragments)
713-713: Link fragments should be valid
(MD051, link-fragments)
🔇 Additional comments (22)
src/pages/concepts/10_countersigning.md (1)
6-6: LGTM; verify link target resolves.Absolute link looks right; please check it renders correctly post‑build.
src/pages/build/identifiers.md (2)
89-89: LGTM.Clearer guidance on hashing entries.
192-192: LGTM.The DNA hash note is accurate and helpful.
src/pages/build/links-paths-and-anchors.md (5)
103-104: LGTM.Live/dead semantics now correctly hinge on validity of create/delete actions.
122-123: LGTM.“Live links” phrasing aligns with the updated semantics.
165-168: LGTM.Stating that invalid link actions aren’t retrievable from a base is precise.
192-193: LGTM.Count behavior note (only live links; counted locally) matches get_links semantics.
151-152: Remove placeholder and complete sentence
- Remove the
(where )fragment and update to:- To get all live _and deleted_ links (where ), along with any deletion actions, use `hdk::link::get_link_details`. + To get all live and deleted links, along with any associated delete-link actions, use `hdk::link::get_link_details`.- Verify the code example still compiles against the current HDK (ensure correct
LinkTypes→LinkTypeFilterconversion).src/pages/concepts/4_dht.md (2)
166-169: LGTM.Updated op destinations (store entry/record/agent activity) are accurate.
192-195: LGTM.Key takeaways accurately reflect warrant behavior and network response.
src/pages/build/entries.md (2)
390-395: LGTM.Good clarification that details include invalid records; advising to check
validation_statusis correct.
425-430: LGTM.Entry details section clearly distinguishes valid vs rejected creation actions.
src/pages/resources/glossary.md (2)
713-714: Validate link fragments on this line (relay, peer discovery).markdownlint reported an invalid fragment here. After adding explicit IDs above, re-run the checker to confirm “#relay” and “#peer-discovery” resolve. If it still flags, consider pinning explicit IDs on those headers too.
558-560: OK: Launcher link and description.Looks good and current.
src/pages/resources/index.md (1)
42-44: LGTM: corrected hApp glossary anchor.The fragment now matches the pinned “#holochain-application-happ” ID.
src/pages/build/must-get-host-functions.md (1)
174-175: Good clarification on warrants’ non-determinism in validation.Accurate constraint; reads well.
src/pages/build/dht-operations.md (1)
9-11: Wording fix looks good.“check DHT operations” grammar correction is correct.
src/pages/build/validation.md (1)
41-48: Good expansion of action‑level validation guidance and tests.The additions are accurate and helpful.
src/pages/build/working-with-data.md (2)
28-41: Nice clarification on “sequence index” and record semantics.Reads clearly; matches CRUD/live‑dead refinements elsewhere.
153-156: CRUD default rules: wording is precise.“oldest‑timestamped, valid … with corresponding valid delete action” is correct.
src/pages/concepts/7_validation.md (1)
297-305: Future feature clearly labeled.Good “Application‑level blocking” caveat; keep until feature lands.
src/pages/concepts/2_application_architecture.md (1)
87-88: Approve changes — verify remaining doc referencesDNA modifiers changes are correct. Occurrences found in src/pages/resources/upgrade/upgrade-holochain-0.5.md (lines 255, 257, 259, 269, 270, 279, 280) that document removal of
origin_timeandquantum_time; keep as upgrade notes or remove/update if you want zero remaining mentions.
pdaoust
force-pushed
the
chore/warrants
branch
from
6746668 to
414ea41
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (7)
src/pages/resources/glossary.md (3)
352-355: Fix broken DeepKey self-link fragment.Heading anchor is “deepkey”; link currently points to “deep-key”.
- [DeepKey](#deep-key) is Holochain's default DPKI implementation. + [DeepKey](#deepkey) is Holochain's default DPKI implementation.
799-801: Fix broken WebAssembly anchor.The heading “WebAssembly (WASM)” generates “#webassembly-wasm”, not “#web-assembly-wasm”.
- a [WebAssembly](#web-assembly-wasm) runtime + a [WebAssembly](#webassembly-wasm) runtime
528-533: Typo in link text (“[#state]”).Remove “#” from the visible link text.
- ... set up initial [source chain](#source-chain) [#state](#state-transition), etc. + ... set up initial [source chain](#source-chain) [state](#state-transition), etc.src/pages/concepts/7_validation.md (4)
42-47: Clarify “DHT remembers validation results” to avoid implying a stored ‘valid’ flag.Receipts are sent to authors; warrants are published and discoverable. Suggest reframing so readers don’t assume authorities persist positive validation state.
-The DHT offers a shortcut --- it remembers the validation results of existing entries. You can ask the validation authorities for the parties' previous transactions if they detected any problems. ... As long as you trust a decent number of your peers to be playing by the rules, the validation result attached to the most recent entry 'proves' the validity of all the entries before it. +You don’t need to re-validate an entire history each time. Validators publish signed **warrants** when they detect invalid data, and authors collect **validation receipts** from authorities for valid operations. In practice, you can consult the agent activity authorities for warrants (evidence of problems) and, where relevant, rely on collected receipts rather than recomputing deep histories.
230-231: Clarify “return the warrant instead.”Consider “may return a warrant in place of invalid data” to indicate behavior can depend on retrieval path and caller expectations.
-When anyone asks for the data at the entry's address, they return the warrant instead. +When anyone asks for the data at the entry's address, they may return the warrant in place of the data.
249-251: Warrant-handling wording: specify what “it’s valid” refers to.Avoid ambiguity by stating “if the warrant claim holds (i.e., the warranted data is invalid)”.
-When an agent receives a warrant, the first step is to check that the warrant is legitimate by trying to fetch and validate the warranted data themselves. If it's valid, they add the warranted agent to their network block list, rejecting all incoming communications from them. If it's invalid, they block the malicious warrant issuer. +When an agent receives a warrant, they first verify the claim by fetching and validating the warranted data. If the claim holds (the warranted data is invalid), they add the warranted agent to their network block list. If the claim fails (the data is valid), they block the malicious warrant issuer.
226-236: Add brief alt text to images for a11y.Many images use empty alt text. Provide concise, descriptive alts.
Example:
-{.sz80p} {.center} +{.sz80p} {.center}
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
.cspell/custom-words.txt(1 hunks)src/pages/build/identifiers.md(4 hunks)src/pages/build/must-get-host-functions.md(3 hunks)src/pages/concepts/4_dht.md(2 hunks)src/pages/concepts/6_crud_actions.md(1 hunks)src/pages/concepts/7_validation.md(13 hunks)src/pages/resources/glossary.md(33 hunks)
🚧 Files skipped from review as they are similar to previous changes (4)
- src/pages/build/must-get-host-functions.md
- src/pages/concepts/6_crud_actions.md
- .cspell/custom-words.txt
- src/pages/build/identifiers.md
🧰 Additional context used
🧠 Learnings (2)
📚 Learning: 2025-09-11T13:19:23.020Z
Learnt from: pdaoust
PR: holochain/docs-pages#597
File: src/pages/resources/glossary.md:933-939
Timestamp: 2025-09-11T13:19:23.020Z
Learning: In the holochain/docs-pages repository, pdaoust prefers glossary definitions to be "future-correct" rather than strictly reflecting current implementation status, to reduce maintenance burden when features are implemented.
Applied to files:
src/pages/resources/glossary.md
📚 Learning: 2025-08-28T23:39:06.675Z
Learnt from: pdaoust
PR: holochain/docs-pages#600
File: src/pages/get-started/install-advanced.md:74-81
Timestamp: 2025-08-28T23:39:06.675Z
Learning: hc-launch may show older Holochain version dependencies (like "holochain 0.5.3") even when other tools show newer versions (like 0.5.5) because hc-launch is only repackaged when necessary for compatibility, not automatically with every Holochain release.
Applied to files:
src/pages/resources/glossary.md
🪛 markdownlint-cli2 (0.17.2)
src/pages/concepts/4_dht.md
170-170: Images should have alternate text (alt text)
(MD045, no-alt-text)
src/pages/resources/glossary.md
713-713: Link fragments should be valid
(MD051, link-fragments)
🔇 Additional comments (8)
src/pages/concepts/4_dht.md (3)
172-173: Validation receipts: LGTM.Keeping receipts here is consistent with the validation flow later in Concepts 7. No action needed.
174-175: Warrant flow reads well and matches the validation chapter.Peers verify the warrant against the claimed invalid data before blocking — good.
192-194: Key‑takeaways on warrants: LGTM. Also: hold merge per PR description.Text looks correct. Operationally, please gate merging until Holochain 0.6 is the recommended release and coordinate merge with PR #597 as noted in the PR description.
src/pages/resources/glossary.md (3)
606-610: Grammar: CALM phrasing.“S/ CALM are / CALM theorem is” for subject–verb agreement; tighten wording.
[Suggest_nitpick_refactor]
- (Holochain works this way; see [CRUD](#create-read-update-delete-crud) for details.) [CALM](#consistency-as-logical-monotonicity-calm-theorem) are logically monotonic, and often retain all state changes, so that the system's final state results from the application of all accumulated state changes. + (Holochain works this way; see [CRUD](#create-read-update-delete-crud) for details.) The [CALM theorem](#consistency-as-logical-monotonicity-calm-theorem) characterizes logically monotonic programs, which often retain all state changes so the system's final state results from applying all accumulated changes.
310-311: Deduplication note: mirrors DHT chapter — good.This explicitly calls out the extra copy at the action base; once Concepts 4 is updated, the set will be consistent.
Please ensure Concepts 4’s “store record” bullet matches this behavior (see my comment there).
712-714: Resolve markdownlint MD051 (invalid link fragments).
- src/pages/resources/glossary.md:354 — DeepKey
- src/pages/resources/glossary.md:800 — WebAssembly
Confirm the headings generate these anchors or update the fragments to match actual heading IDs; then run markdownlint across src/pages (e.g. npx markdownlint-cli2 "src/**/*.md") to catch and fix remaining MD051 issues.
src/pages/concepts/7_validation.md (2)
153-156: Be precise: authorities receive operations, not entries.Small wording fix.
[Suggest_nitpick_refactor]
-When an authority **receives an entry for validation**, the flow is different. +When an authority **receives a DHT operation for validation**, the flow is different.
322-323: Typo: “to by fetched” → “to be fetched”.[raise_nitpick_refactor]
-* Genesis self-checking occurs before an agent joins a network, catching basic errors that don't require dependencies to by fetched. +* Genesis self-checking occurs before an agent joins a network, catching basic errors that don't require dependencies to be fetched.
pdaoust
force-pushed
the
chore/warrants
branch
from
414ea41 to
3399146
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
src/pages/concepts/4_dht.md (1)
167-168: Align ‘store record’ semantics with glossary (duplicate entry at action basis).
This was flagged earlier and still reads as “hold the action” only; glossary states a copy of the entry is also stored at the action’s base.-* A **store record** operation, containing the entry and the action, goes to the **record authorities** whose arcs cover the action's hash. When it's integrated, the authorities will hold the action at that basis address. +* A **store record** operation, containing the entry and the action, goes to the **record authorities** whose arcs cover the action's hash. When it's integrated, the authorities will hold the action and a duplicate of the entry at that basis address.
🧹 Nitpick comments (5)
src/pages/build/must-get-host-functions.md (1)
121-121: Variable reference needs updating.There's a mismatch between the variable name defined (
lower_bound) and the variable used in thetake_whilepredicate (take_until_timestamp).Fix the variable reference:
- .take_while(|a| a.timestamp() >= take_until_timestamp) + .take_while(|a| a.timestamp() >= &lower_bound)src/pages/build/identifiers.md (3)
38-41: Fix nested-list indentation and stray token (“Any”) to satisfy markdownlint (MD007) and remove a typo.
Current bullets are indented 4 spaces and line 39 ends with a dangling “Any”.Apply:
-* 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, or `AnyDhtHash` or `ExternalHash`). +* 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). + * `AnyLinkableHash` is the hash of anything that can be linked to or from (that is, all of the above, or `AnyDhtHash` or `ExternalHash`).
89-105: Remove unused import in the example.
use chrono::DateTime;isn’t used; trim to avoid copy/paste confusion.use hdk::hash::*; use movie_integrity::*; -use chrono::DateTime;
192-198: Nit: Reference both hdk and hdi versions of dna_info for consistency.
Example useshdk::info::dna_info, reference lists onlyhdi::info::dna_info.* [`hdk::info::agent_info`](https://docs.rs/hdk/latest/hdk/info/fn.agent_info.html) * [`holochain_integrity_types::action::Action#author`](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/action/enum.Action.html#method.author) * [`holo_hash::HoloHash<P>#from_raw_32`](https://docs.rs/holo_hash/latest/src/holo_hash/hash.rs.html#217-219) (must be enabled by `hashing` feature flag) +* [`hdk::info::dna_info`](https://docs.rs/hdk/latest/hdk/info/fn.dna_info.html) * [`hdi::info::dna_info`](https://docs.rs/hdi/latest/hdi/info/fn.dna_info.html)src/pages/concepts/4_dht.md (1)
174-175: Clarify warrant storage and that blocking is a peer choice, not automatic.File: src/pages/concepts/4_dht.md (lines 174–175) — Replace the sentence implying an automatic network-enforced block with wording that warrants are attached to an agent’s AgentActivity and gossiped to agent-activity authorities, and that peers receiving a valid warrant may take defensive actions (e.g., block the warranted agent and delete locally-held invalid data) — these actions are permitted/recommended, not protocol-enforced automatic kills.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
.cspell/custom-words.txt(1 hunks)src/pages/build/identifiers.md(4 hunks)src/pages/build/must-get-host-functions.md(3 hunks)src/pages/concepts/4_dht.md(2 hunks)src/pages/concepts/6_crud_actions.md(1 hunks)src/pages/concepts/7_validation.md(13 hunks)src/pages/resources/glossary.md(33 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- .cspell/custom-words.txt
- src/pages/concepts/6_crud_actions.md
🧰 Additional context used
🧠 Learnings (3)
📚 Learning: 2025-09-11T13:19:23.020Z
Learnt from: pdaoust
PR: holochain/docs-pages#597
File: src/pages/resources/glossary.md:933-939
Timestamp: 2025-09-11T13:19:23.020Z
Learning: In the holochain/docs-pages repository, pdaoust prefers glossary definitions to be "future-correct" rather than strictly reflecting current implementation status, to reduce maintenance burden when features are implemented.
Applied to files:
src/pages/resources/glossary.md
📚 Learning: 2025-08-28T23:39:06.675Z
Learnt from: pdaoust
PR: holochain/docs-pages#600
File: src/pages/get-started/install-advanced.md:74-81
Timestamp: 2025-08-28T23:39:06.675Z
Learning: hc-launch may show older Holochain version dependencies (like "holochain 0.5.3") even when other tools show newer versions (like 0.5.5) because hc-launch is only repackaged when necessary for compatibility, not automatically with every Holochain release.
Applied to files:
src/pages/resources/glossary.md
📚 Learning: 2025-09-18T21:17:38.273Z
Learnt from: pdaoust
PR: holochain/docs-pages#607
File: src/pages/build/entries.md:342-345
Timestamp: 2025-09-18T21:17:38.273Z
Learning: In Holochain, `hdk::entry::get` filters out invalid record data and returns None for invalid or missing records, while `get_details` returns records regardless of validation status with metadata indicating their validation state. The `must_get*` functions operate in a different context (validation) and don't relate cleanly to the `get*` functions.
Applied to files:
src/pages/build/must-get-host-functions.md
🪛 markdownlint-cli2 (0.17.2)
src/pages/concepts/7_validation.md
186-186: Images should have alternate text (alt text)
(MD045, no-alt-text)
226-226: Images should have alternate text (alt text)
(MD045, no-alt-text)
234-234: Images should have alternate text (alt text)
(MD045, no-alt-text)
242-242: Images should have alternate text (alt text)
(MD045, no-alt-text)
src/pages/resources/glossary.md
713-713: Link fragments should be valid
(MD051, link-fragments)
src/pages/build/identifiers.md
39-39: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
40-40: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
src/pages/build/must-get-host-functions.md
18-18: Link fragments should be valid
(MD051, link-fragments)
🔇 Additional comments (22)
src/pages/resources/glossary.md (7)
9-9: Enhanced action definition with warrant references.The addition of warrant authorship as a type of action broadens the definition appropriately to include this important immune system mechanism.
47-47: Improved agent address definition clarity.The updated definition better explains how agent addresses are used in the DHT for locating transport addresses and selecting validation authorities.
466-472: Added explicit anchors for hApp-related terms.The addition of explicit anchor IDs (
#happ-bundle,#happ-manifest,#web-happ) improves cross-referencing capabilities throughout the documentation.
534-536: New "Integrate" glossary term with clear definition.The definition of "integrate" as applying a DHT operation to existing state at a basis address is technically accurate and helps clarify DHT operation semantics.
826-828: New "Scratch space" definition aligns with validation workflow.The definition accurately describes the staging area concept used in validation and commit processes, consistent with the terminology used in other files in this PR.
956-958: New "Wind Tunnel" glossary entry.The addition of Wind Tunnel as a test orchestrator provides useful reference information for developers working with scenario tests.
713-713: Relay fragment exists — no action needed.
Found "#### Relay" in src/pages/resources/glossary.md at line 773; relay links at lines 713 and 893 resolve correctly.src/pages/build/must-get-host-functions.md (3)
18-18: Minor grammatical improvement.The change from "as as" to "as a" fixes a typo and improves readability.
108-108: Logic correction for spam detection time window.The change from a future-looking spam window to a past-looking window makes more logical sense for spam detection. Using
lower_bound = timestamp - 60scorrectly identifies recent activity in the past 60 seconds from the current action's timestamp.
174-174: Enhanced warrant explanation with practical guidance.The replacement of the forward-looking note with detailed warrant explanation provides much more practical guidance for developers. The clarification about warrant limitations in validation callbacks and the guidance for comprehensive validation coverage is valuable.
src/pages/concepts/7_validation.md (7)
18-18: Updated section heading for better organization.The change to "System validation and validation-like things" better reflects the broader scope of system-level validation concepts covered in this section.
40-45: Improved validation result terminology and warrant integration.The changes from "validation receipts" to "validation results" and the detailed explanation of warrant generation and distribution provide clearer and more accurate descriptions of the validation process and immune system mechanisms.
90-90: Enhanced authoring workflow description with scratch space terminology.The introduction of "scratch space" terminology and the more detailed description of the staging process aligns well with the glossary definitions and provides better clarity about the validation workflow.
222-238: Comprehensive warrant workflow documentation.The detailed description of warrant creation, blocking behavior, and distribution to agent activity authorities provides excellent documentation of Holochain's immune system mechanisms. The step-by-step process helps developers understand how invalid data handling works.
249-251: Important warrant verification guidance.The explanation of how agents should verify warrants before taking action is crucial for preventing abuse of the warrant system and maintaining network integrity.
275-287: Well-organized system validation section.The restructuring into specific subsections (hashes/signatures/chain continuity, source chain forks, etc.) provides better organization and makes the system-level validation concepts more accessible.
297-305: Clear future feature documentation.The application-level blocking section is appropriately marked as a future feature and provides good conceptual guidance for developers to understand the intended broader immune system capabilities.
src/pages/build/identifiers.md (3)
33-33: Clarified DnaHash wording looks good.
Accurate, improves specificity about the DNA’s network.
204-227: Entry/link address-field guidance reads well.
Clear examples; matches current HDK patterns.
166-181: Version pins & feature flag — use workspace versions and add holo_hashCargo.lock is missing so resolved versions can't be confirmed. In src/pages/build/identifiers.md (lines 166–181) the docs pin hdi = "=0.6.5" and hdk = "=0.5.5" (lines 168–169) while the zome snippet only shows hdi = { workspace = true } (line 178) and lacks holo_hash.
- Replace exact pins with workspace references or update the pinned versions to match Cargo.lock once available.
- If holo_hash is required, add it to both snippets: workspace.dependencies should include holo_hash = "=" and the zome Cargo.toml snippet should include holo_hash = { workspace = true, features = ["hashing"] }.
- Commit or provide Cargo.lock (or state authoritative workspace versions) so the docs and repo stay consistent.
src/pages/concepts/4_dht.md (2)
172-173: Validation receipt flow improvement looks correct.
Accurately reflects “receipt after validation” sequencing.
192-194: Warrants bullets read well.
Concise and accurate summary of outcomes and peer actions.
jost-s
left a comment
jost-s
left a comment
There was a problem hiding this comment.
LGTM
All my comments are suggestions. Except the update of the variable name, that I'm requesting to change.
Co-authored-by: Jost <28270981+jost-s@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
src/pages/build/links-paths-and-anchors.md (1)
151-163: LGTM: get_link_details describes live+deleted retrieval.This resolves prior confusion.
🧹 Nitpick comments (10)
src/pages/build/identifiers.md (3)
39-41: Remove stray word “Any”.Line 39 ends with an extra “Any”. Drop it to avoid reader confusion.
- * `AnyDhtHash` is the hash of any kind of addressable content (actions, entries, and agent public keys). Any + * `AnyDhtHash` is the hash of any kind of addressable content (actions, entries, and agent public keys).
92-95: Drop unused import in snippet.
use chrono::DateTime;isn’t used.-use chrono::DateTime;
96-105: Clarify raw length for from_raw_36.
EntryHash::from_raw_36expects 36 raw bytes (no 3‑byte multihash prefix). Consider adding a comment to prevent misuse.- director_entry_hash: EntryHash::from_raw_36(vec![/* hash of Sergio Leone entry */]), + // 36 raw bytes (no 3‑byte multihash prefix) + director_entry_hash: EntryHash::from_raw_36(vec![/* raw 36 bytes of Sergio Leone entry hash */]),src/pages/resources/glossary.md (2)
392-393: Tighten E2EE transport phrasing and confirm accuracy.WebRTC typically uses DTLS-SRTP for encryption (not generic “TLS”). Suggest: “E2EE (currently WebRTC with DTLS-SRTP; connections may relay but remain end-to-end encrypted).” Please confirm this is accurate for the current conductor/transport.
-Holochain's node-to-node network communications, including gossip, publishing, and remote calls, use E2EE (currently WebRTC over TLS). +Holochain's node-to-node network communications, including gossip, publishing, and remote calls, use E2EE (currently WebRTC with DTLS‑SRTP).
606-610: Grammar nit: clarify subject.“CALM” is singular as a theorem; tweak for flow.
- (Holochain works this way; see CRUD for details.) CALM are logically monotonic, + (Holochain works this way; see CRUD for details.) The CALM theorem is about logical monotonicity,src/pages/concepts/7_validation.md (5)
55-58: Fix pluralization.Minor grammar issue.
-Entries and action can be retrieved by hash, as can entire sequences of a source chain. +Entries and actions can be retrieved by hash, as can entire sequences of a source chain.
186-186: Add alt text for accessibility (image).Images lack alt text; add concise descriptions.
-{.sz80p} {.center} +{.sz80p} {.center}
226-226: Add alt text for accessibility (image).-{.sz80p} {.center} +{.sz80p} {.center}
234-234: Add alt text for accessibility (image).-{.sz80p} {.center} +{.sz80p} {.center}
242-242: Add alt text for accessibility (image).-{.sz80p} {.center} +{.sz80p} {.center}
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
src/pages/build/entries.md(3 hunks)src/pages/build/identifiers.md(4 hunks)src/pages/build/links-paths-and-anchors.md(5 hunks)src/pages/build/must-get-host-functions.md(4 hunks)src/pages/concepts/7_validation.md(13 hunks)src/pages/resources/glossary.md(33 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- src/pages/build/must-get-host-functions.md
- src/pages/build/entries.md
🧰 Additional context used
🧠 Learnings (2)
📚 Learning: 2025-09-11T13:19:23.020Z
Learnt from: pdaoust
PR: holochain/docs-pages#597
File: src/pages/resources/glossary.md:933-939
Timestamp: 2025-09-11T13:19:23.020Z
Learning: In the holochain/docs-pages repository, pdaoust prefers glossary definitions to be "future-correct" rather than strictly reflecting current implementation status, to reduce maintenance burden when features are implemented.
Applied to files:
src/pages/resources/glossary.md
📚 Learning: 2025-08-28T23:39:06.675Z
Learnt from: pdaoust
PR: holochain/docs-pages#600
File: src/pages/get-started/install-advanced.md:74-81
Timestamp: 2025-08-28T23:39:06.675Z
Learning: hc-launch may show older Holochain version dependencies (like "holochain 0.5.3") even when other tools show newer versions (like 0.5.5) because hc-launch is only repackaged when necessary for compatibility, not automatically with every Holochain release.
Applied to files:
src/pages/resources/glossary.md
🪛 markdownlint-cli2 (0.17.2)
src/pages/concepts/7_validation.md
186-186: Images should have alternate text (alt text)
(MD045, no-alt-text)
226-226: Images should have alternate text (alt text)
(MD045, no-alt-text)
234-234: Images should have alternate text (alt text)
(MD045, no-alt-text)
242-242: Images should have alternate text (alt text)
(MD045, no-alt-text)
src/pages/resources/glossary.md
713-713: Link fragments should be valid
(MD051, link-fragments)
🔇 Additional comments (9)
src/pages/build/identifiers.md (1)
166-182: Version pins must match the recommended Holochain 0.6 at merge time.Before merging when 0.6 becomes the recommended release, update these exact versions (hdi/hdk/holo_hash) to the correct 0.6-compatible numbers or replace with workspace pins as appropriate. Also verify the hashing feature flag note still applies to that version.
src/pages/build/links-paths-and-anchors.md (4)
103-104: Good: precise live/dead definition for links.The validity-gated definition reads clearly and aligns with the rest of the docs.
122-138: LGTM: get_links builder example.Solid example; shows Network strategy and post-filter to EntryHash cleanly.
165-168: Nice clarification: invalid link ops aren’t retrievable.Sets correct expectations for callers.
191-193: Count semantics note is helpful.Good to state “live only” parity with get_links.
src/pages/resources/glossary.md (3)
773-776: Relay definition reads well.Clear replacement for “proxy relay”.
338-343: Good: three-op example remains accurate and helpful.Keeps agent-activity op in view.
114-117: Bootstrap service definition aligns with basis/DNA-hash framing.No issues.
src/pages/concepts/7_validation.md (1)
249-251: Solid operational guidance for encountering warrants.Clear and actionable.
pdaoust
force-pushed
the
chore/warrants
branch
from
1d910a6 to
46a15f2
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (3)
src/pages/build/must-get-host-functions.md (1)
121-121: Confirm ordering assumption fortake_while.This relies on
must_get_agent_activityreturning actions in reverse‑chronological order fromprev_action_hashbackward. If that guarantee ever changes, prefer a simple.filter(|a| a.timestamp() >= lower_bound)(loses early‑exit, but correct regardless of ordering).src/pages/build/identifiers.md (2)
33-33: Resolved prior suggestion: DnaHash wording LGTM.Matches the earlier review recommendation; reads clearly and links to the right section.
192-192: Rephrase to “In every DNA…” LGTM.Matches prior reviewer guidance; clearer mental model.
🧹 Nitpick comments (5)
src/pages/build/must-get-host-functions.md (1)
18-19: Fix invalid local anchor fragment per markdownlint MD051.Change the fragment to match the section slug for “
must_get_valid_record”.-... [`must_get_valid_record`](#must-get-valid-record). +... [`must_get_valid_record`](#must_get_valid_record).If your site generator doesn’t preserve underscores in slugs, consider adding an explicit anchor ID to the header.
src/pages/build/identifiers.md (3)
39-41: Fix nested list indentation (markdownlint MD007).Reduce indentation on nested bullets to 2 spaces for consistent rendering.
- * `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, or `AnyDhtHash` or `ExternalHash`). + * `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, or `AnyDhtHash` or `ExternalHash`).
92-105: Remove unused import in snippet.
use chrono::DateTime;isn’t used and may distract readers.use hdk::hash::*; use movie_integrity::*; -use chrono::DateTime;
289-289: Align reference with example: prefer hdk::info::dna_info.Examples use
hdk::info::dna_info; update the reference for consistency.-* [`hdi::info::dna_info`](https://docs.rs/hdi/latest/hdi/info/fn.dna_info.html) +* [`hdk::info::dna_info`](https://docs.rs/hdk/latest/hdk/info/fn.dna_info.html)src/pages/resources/glossary.md (1)
392-392: Networking phrasing: avoid “WebRTC over TLS”.WebRTC already provides E2EE via DTLS/SRTP. Suggest clearer wording.
-A channel between two nodes in a public network that allows them to transfer secret messages that cannot be decrypted by eavesdroppers. Holochain's node-to-node [network](#network) communications, including [gossip](#gossip), [publishing](#publish), and [remote calls](#remote-call), use E2EE (currently WebRTC over TLS). +A channel between two nodes in a public network that allows them to transfer secret messages that cannot be decrypted by eavesdroppers. Holochain's node-to-node [network](#network) communications, including [gossip](#gossip), [publishing](#publish), and [remote calls](#remote-call), use E2EE (currently WebRTC using DTLS/SRTP).
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
src/pages/build/identifiers.md(4 hunks)src/pages/build/must-get-host-functions.md(4 hunks)src/pages/resources/glossary.md(33 hunks)
🧰 Additional context used
🧠 Learnings (4)
📚 Learning: 2025-09-11T13:19:23.020Z
Learnt from: pdaoust
PR: holochain/docs-pages#597
File: src/pages/resources/glossary.md:933-939
Timestamp: 2025-09-11T13:19:23.020Z
Learning: In the holochain/docs-pages repository, pdaoust prefers glossary definitions to be "future-correct" rather than strictly reflecting current implementation status, to reduce maintenance burden when features are implemented.
Applied to files:
src/pages/resources/glossary.md
📚 Learning: 2025-09-19T17:48:55.415Z
Learnt from: pdaoust
PR: holochain/docs-pages#607
File: src/pages/resources/glossary.md:312-315
Timestamp: 2025-09-19T17:48:55.415Z
Learning: In the holochain/docs-pages repository, pdaoust's slugification code automatically converts camelCase/PascalCase words to hyphenated format (e.g., "DeepKey" becomes "deep-key"), so explicit anchors are not needed for such headings.
Applied to files:
src/pages/resources/glossary.md
📚 Learning: 2025-08-28T23:39:06.675Z
Learnt from: pdaoust
PR: holochain/docs-pages#600
File: src/pages/get-started/install-advanced.md:74-81
Timestamp: 2025-08-28T23:39:06.675Z
Learning: hc-launch may show older Holochain version dependencies (like "holochain 0.5.3") even when other tools show newer versions (like 0.5.5) because hc-launch is only repackaged when necessary for compatibility, not automatically with every Holochain release.
Applied to files:
src/pages/resources/glossary.md
📚 Learning: 2025-09-18T21:17:38.273Z
Learnt from: pdaoust
PR: holochain/docs-pages#607
File: src/pages/build/entries.md:342-345
Timestamp: 2025-09-18T21:17:38.273Z
Learning: In Holochain, `hdk::entry::get` filters out invalid record data and returns None for invalid or missing records, while `get_details` returns records regardless of validation status with metadata indicating their validation state. The `must_get*` functions operate in a different context (validation) and don't relate cleanly to the `get*` functions.
Applied to files:
src/pages/build/must-get-host-functions.md
🪛 markdownlint-cli2 (0.17.2)
src/pages/resources/glossary.md
713-713: Link fragments should be valid
(MD051, link-fragments)
src/pages/build/identifiers.md
39-39: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
40-40: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
src/pages/build/must-get-host-functions.md
18-18: Link fragments should be valid
(MD051, link-fragments)
🔇 Additional comments (9)
src/pages/build/must-get-host-functions.md (2)
108-108: Past-60s window bound looks correct.Using
saturating_subto derivelower_boundis appropriate and resilient to clock skew.
174-175: Warrants guidance is accurate and scoped to deterministic validation.Clear statement of non-co-location/delivery guarantees and why warrants can’t be used in callbacks. LGTM.
src/pages/resources/glossary.md (6)
35-41: Agent activity/operation additions read clearly.Accurately ties activity, basis addresses, and authorities together.
466-473: New anchors for hApp bundle/manifest LGTM.Improves link stability across the docs.
773-776: Relay term introduction LGTM.Clear, concise definition aligned with transport notes.
914-915: Validating DHT now referencing warrants LGTM.Good alignment with 0.6 warrant semantics.
939-943: Warrant definition and effect LGTM.Nicely explains purpose and social effect.
713-713: Resolved — 'Peer-to-peer' anchor present; links resolve. src/pages/resources/glossary.md:711 contains "#### Peer-to-peer" and multiple inbound links reference (#peer-to-peer); MD051 is a false positive.src/pages/build/identifiers.md (1)
166-181: Release-day check: verify Holochain 0.6 toolchain pins before merge.
This file pins hdi="=0.6.5", hdk="=0.5.5", holo_hash="=0.5.5" and contains a TODO(upgrade); confirm these match the recommended Holochain 0.6 toolchain on release day and update the Cargo.toml examples if needed.
Location: src/pages/build/identifiers.md (TODO ~line 160; pins ~lines 168–170).
|
✔️ d0fcd4a...27ffb70 - Conventional commits check succeeded. |
| 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 the [unique identifier for the DNA's network](/build/working-with-data/#storage-locations-and-privacy). |
There was a problem hiding this comment.
| * `DnaHash` is the hash of the DNA bundle (including any DNA modifiers passed in at installation or cloning time) and the [unique identifier for the DNA's 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 acts as the [unique identifier for the DNA's network](/build/working-with-data/#storage-locations-and-privacy). |
| * 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` or `ExternalHash`). |
There was a problem hiding this comment.
I don't think this change is necessary -- the above types are included in AnyDhtHash, and ExternalHash is also above.
|
|
||
| !!! info Invalid links | ||
| There is no way to retrieve invalid link creation or deletion actions from a base. | ||
| !!! |
There was a problem hiding this comment.
Huh, seems inconsistent with how other calls will return invalid data. Should we have an issue to track?
| 1. An individual [cell](#cell) in a Holochain [network](#network). | ||
| 2. A [conductor](#conductor) hosting one or more cells. |
There was a problem hiding this comment.
| 1. An individual [cell](#cell) in a Holochain [network](#network). | |
| 2. A [conductor](#conductor) hosting one or more cells. | |
| 2. An individual [cell](#cell) in a Holochain [network](#network). | |
| 3. A [conductor](#conductor) hosting one or more cells. |
| To convert a [record](#record) into one or more [DHT operations](#dht-operation) and send them to the respective [validation authorities](#validation-authority) for [validation](#validation-rule), transformation into [record data](#record-data), and storage. This happens after it has passed the author's own copy of the [validation rules](#validation-rule). The validation authorities who are responsible for that entry's [address](#address) receive it, validate it, and if it's valid, store a copy of it and pass a [validation receipt](#validation-receipt) back to the author. | ||
| To convert a [record](#record) into one or more [DHT operations](#dht-operation) and send them to the respective [validation authorities](#validation-authority) for [validation](#validation-rule), transformation into [record data](#record-data), and storage. This happens after it has passed the author's own copy of the [validation rules](#validation-rule). The validation authorities who are responsible for the operations' [basis addresses](#basis-address) validate them, and if they're valid, store a copy of them and pass [validation receipts](#validation-receipt) back to the author. (See also [integrate](#integrate)). | ||
|
|
||
| #### Quantized gossip |
There was a problem hiding this comment.
| #### Quantized gossip | |
| #### Gossip |
Closes #596 and #602 , but also ended up catching a lot of obsolete info, typos, etc. Do not merge until 0.6 is the new recommended release; should be merged in tandem with #597 .
Summary by CodeRabbit
Documentation
Chores