Build guide: zome functions and lifecycle callbacks

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

@@ -25,6 +25,7 @@ runtimes
 sandboxed
 sandboxing
 scaffolder
+snapshotted
 spacebar
 todo
 todos

src/pages/_data/navigation/mainNav.json5

@@ -25,7 +25,12 @@
       ]
     },
     { title: "Build", url: "/build/", children: [
-        { title: "Application Structure", url: "/build/application-structure/", children: []},
+        { title: "Application Structure", url: "/build/application-structure/", children: [
+          { title: "Zomes", url: "/build/zomes/", children: [
+            { title: "Lifecycle Events and Callbacks", url: "/build/callbacks-and-lifecycle-hooks/" },
+            { title: "Zome Functions", url: "/build/zome-functions/" },
+          ] },
+        ]},
         { title: "Working with Data", url: "/build/working-with-data/", children: [
           { title: "Identifiers", url: "/build/identifiers/" },
           { title: "Entries", url: "/build/entries/" },

src/pages/build/application-structure.md

@@ -6,7 +6,9 @@ title: Application Structure
 ### In this section {data-no-toc}
 
 * Application Structure (this page)
-    * Zomes (coming soon) --- integrity vs coordinator, how to structure and compile
+    * [Zomes](/build/zomes/) --- integrity vs coordinator, how to structure and compile
+        * [Lifecycle Events and Callbacks](/build/callbacks-and-lifecycle-hooks/) --- writing functions that respond to events in a hApp's lifecycle
+        * [Zome Functions](/build/zome-functions/) --- writing your hApp's back-end API
     * DNAs (coming soon) --- what they're used for, how to specify and bundle
     * hApps (coming soon) --- headless vs UI-based, how to bundle and distribute
 :::
@@ -17,9 +19,9 @@ There are a few basic units of composability and packaging you'll need to know a
 
 ## Zomes, DNAs, and hApps
 
-### Zomes
+### Zome
 
-The smallest unit in a hApp is called a **zome** (a play on DNA chromosomes) It's the actual binary code that runs in Holochain's [WebAssembly](https://webassembly.org/) VM.
+The smallest unit in a hApp is called a **zome** (a play on DNA chromosomes). It's the actual binary code that runs in Holochain's [WebAssembly](https://webassembly.org/) sandbox.
 
 !!! info Why WebAssembly?
 
@@ -32,38 +34,42 @@ We chose WebAssembly because:
 
 !!!
 
-A zome has access to Holochain's host API and also exposes functions of its own. Some of these functions are **required callbacks** and some of them you invent yourself to create your back end's API.
+A zome has access to Holochain via the **host API** and also exposes functions of its own. Some of these functions are **callbacks** and some of them you invent yourself to create your back end's API.
 
 There are two kinds of zome:
 
-* An **integrity zome** defines a set of data types --- your application's schema --- and validation rules for operations that create, update, or delete data of those types. If you're used to thinking of apps in terms of [model-view-controller (MVC)](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller), it's like your application's model.
-* A **coordinator zome** defines a set of functions for interacting with data and peers. You can think of it as your application's controller.
+* An **integrity zome** defines a set of data types --- your application's schema --- and validation rules for operations that create, update, or delete data of those types; in other words, your data model.
+* A **coordinator zome** defines a set of functions for interacting with data, peers, and other coordinator zomes.
 
-Zomes are usually created as pairs --- an integrity zome that defines a portion of your schema and a coordinator zome that defines <abbr title="create, read, update, delete">CRUD</abbr> functions for that schema. You don't have to do it this way though; coordinator zomes don't need an integrity zome if they don't manipulate data, or they can depend on multiple integrity zomes, or multiple coordinators can depend on the same integrity zome.
+Zomes are usually created as pairs --- an integrity zome that defines a data model and a coordinator zome that defines functions for operating on this model. You don't have to do it this way though; coordinator zomes don't need an integrity zome if they don't manipulate data, or they can depend on multiple integrity zomes, or multiple coordinators can depend on the same integrity zome.
 
 If you mean for your zomes to be reused by other projects, you can share them via a public Git repository or [crates.io](https://crates.io) (tag your crates with `#holochain` so others can find them).
 
-### DNAs
+[Read more on the Zomes page](/build/zomes/).
 
-One or more zomes are bundled into a **DNA**. When two or more participants install and run a DNA, an isolated peer-to-peer network is created among them to interact and store shared data.
+### DNA
+
+One or more zomes are bundled into a **DNA**, including at least one integrity zome. When two or more agents install and run a DNA, a new peer-to-peer network is created among them to interact and store shared data.
 
 **A DNA, and the network created for it, is uniquely defined by its integrity zomes, plus any modifiers.** The hash of the integrity zomes plus modifiers is called the **DNA hash**, and is the unique identifier for the network.
 
-!!! info Why not coordinator zomes?
+!!! info Why are coordinator zomes not included in the DNA hash?
+
+Coordinator zomes are bundled with a DNA, but they don't contribute to its hash's uniqueness. That's because they don't constitute the 'rules of the game' for a network like integrity zomes do.
 
-Coordinator zomes are bundled with a DNA, but they don't contribute to its uniqueness. This lets you hot-swap coordinators as you fix bugs and add features, without causing the DNA to **fork** a new network. The only things that should cause a fork are changes to integrity code --- the 'rules of the game' for the participants.
+This means you can hot-swap coordinators as you fix bugs and add features, without changing the DNA hash and creating a new network, which we sometimes call **forking**. The only things that should cause a fork are changes to integrity code.
 
 !!!
 
-Because each DNA has its own isolated peer network and data store, you can use the DNA concept to come up with creative approaches to privacy and access, separation of responsibilities, or data retention.
+Because each DNA has its own separate peer network and data store, you can use the DNA concept to come up with creative approaches to [privacy](https://dialnet.unirioja.es/servlet/articulo?codigo=8036267) and access, separation of responsibilities, or data retention.
 
 ### hApp
 
-Multiple DNAs come together in a **hApp** (Holochain app). Each DNA fills a named **role** in the hApp, and can be seen as a [microservice](https://en.wikipedia.org/wiki/Microservices).
+One or more DNAs come together in a **hApp** (Holochain app). Each DNA fills a named **role** in the hApp, and you can think of it like a [microservice](https://en.wikipedia.org/wiki/Microservices).
 
-Each peer generates its own public/private key pair when they install a hApp. Their public key acts as their **agent ID** which identifies them as a participant in all the networks created for all the DNAs in the hApp. When a DNA is activated, it's bound to this key pair and becomes a DNA instance or **cell**.
+Each agent generates their own public/private key pair when they install a hApp. Their public key acts as their **agent ID** which identifies them as a participant in all the networks created for all the DNAs in the hApp. When a DNA is activated, it's bound to this key pair and becomes a **cell**.
 
-The hApp can specify a few provisioning strategies for its DNAs:
+The hApp can specify two provisioning strategies for its DNAs:
 
 * A cell can be instantiated at app installation time.
 * A new cell can be **cloned** from an existing DNA at any time _after the hApp is installed_, with an optional limit on the number of clones.
@@ -76,7 +82,7 @@ The big difference with peer-to-peer stacks like Holochain is that **all the cod
 
 That means that a DNA doesn't exist as some piece of code that runs 'out there somewhere' --- instead it runs from the perspective of an individual. DNA + agent = cell.
 
-There can still be bots or system-level services that do automated tasks. Those functions just have to be handled by one of the peers, and that peer doesn't have to be a human.
+There can still be bots or system-level services that do automated tasks. Those functions just have to be handled by one of the agents, and that agent doesn't have to be a human.
 
 !!!