Practical guide to using App / Cell Lifecycle

[mattyg]

Must include:

• code examples
• practical, terse explanation of how to use
• gotchas

Potential topics include:

• App/cell lifecycle
  ```mermaid
  sequenceDiagram
  participant User
  participant Client
  participant Launcher
  participant Conductor
  participant Network

        Note over User,Network: Installation
        User->>Launcher: app bundle and network seed
        activate Launcher
        Launcher->>Conductor: app bundle, optional network seed, and optional membrane proof
        deactivate Launcher
        activate Conductor
        Conductor->>Conductor: generate new agent key pair
        opt
            Conductor->>Conductor: register new key pair with DPKI service
        end
        loop for each role in app bundle
            create participant Integrity zome
            Conductor->>Integrity zome: store integrity zome bytecode in database
            create participant Coordinator zome
            Conductor->>Coordinator zome: store coordinator zome bytecode in database
            Conductor->>Conductor: spin up WASM VM with integrity zome bytecode
            Conductor->>Integrity zome: call `entry_defs()`
            Integrity zome-->>Conductor: entry types definitions
            Conductor->>Conductor: store metadata, WASM bytecode, and entry type definitions in database
            opt provisioning is not set to deferred
                Conductor->>Integrity zome: call `genesis_self_check(membrane_proof)`
                break `genesis_self_check()` fails
                    Conductor->>Conductor: cell is disabled
                end
                Conductor->>Conductor: initialize source chain with `DNA`, agent public key, and `AgentValidationPkg` actions (genesis actions)
                Note over Conductor: Do not self-validate genesis actions, dependencies are inaccessible
                Conductor->>Network: Discover list of initial network peers
                Network-->>Conductor: initial network peers
                Conductor->>Network: Establish connections with peers
                Note over Conductor,Network: publish genesis actions -- see elsewhere for publish sequence
            end
        end
        Note over User,Network: Usage
        Note over User,Coordinator zome: function call -- simplified sequence, see below for full sequence
        Client->>Conductor: call function `foo()` in coordinator zome
        activate Conductor
        Conductor->>Conductor: check capability token
        opt no function has been called in app yet
            Conductor->>Coordinator zome: call `init()`
            activate Coordinator zome
            Coordinator zome-->>Conductor: result of `init()`
            deactivate Coordinator zome
            break ❌ result is failure
                Conductor-->>Client: failure
            end
        end
        Conductor->>Coordinator zome: call `foo()`
        activate Coordinator zome
        Coordinator zome-->Conductor: result of call
        deactivate Coordinator zome
        Conductor->>Conductor: validate written data
        par publish data
            Conductor->>Network: send written data for validation
        and return result of call
            Conductor-->>Client: result of call
            deactivate Conductor
        end
        Note over Client,Conductor: (future) activating deferred cells
        Client->>Conductor: call app API function `????` on app role `bar`
        activate Conductor
        Conductor->>Conductor: instantiate cell from DNA that fills role `bar`, name it `bar_qux`
        Conductor-->>Client: result of activation attempt
        deactivate Conductor
        Note right of Conductor: activating a deferred cell follows same sequence as instantiating app's initial cells above
        Note over Client,Conductor: cloning a DNA
        Client->>Conductor: call app API function `CreateCloneCell` on app role `bar` with name `bar_qux`
        activate Conductor
        Conductor->>Conductor: clone and instantiate cell from DNA that fills role `bar`, name it `bar_qux`
        Note right of Conductor: instantiating a cloned cell follows same sequence as instantiating app's initial cells above
        Conductor-->>Client: result of clone attempt
        Note over Client,Conductor: disabling a clone cell
        Client->>Conductor: call `DisableCloneCell` with clone cell ID `baz_qux`
        Conductor->Conductor: wait for any running functions in cell `baz_qux` to finish
        Conductor->>Conductor: disable network communications and function bindings for cell
        Conductor-->>Client: result of attempt to disable
        Note over Client,Conductor: enabling a cell
        Client->>Conductor: call `EnableCloneCell` with clone cell ID `baz_qux`
        Conductor->Conductor: resume network communications for cell and re-bind cell's functions
        Conductor-->>Client: result of attempt to enable
        Note over Client,Network: conductor is unable to connect to other peers, either because of network failure or because peers have blocked agent
        Coordinator zome->>Conductor: request DHT data
        activate Conductor
        Conductor-xNetwork: ❌ connection attempt fails
        Conductor->>Conductor: attempt to fetch DHT data from local store or cache
        Conductor-->>Coordinator zome: locally stored data or empty result
        Note over Client,Network: uninstalling an app
        loop for each cell in app
            Conductor->>Conductor: disable cell
            Conductor->>Conductor: remove cell's source chain data
            opt cell is last locally installed instance of DNA
                Conductor->>Conductor: remove DNA's validated and/or cached DHT data
                destroy Coordinator zome
                Conductor-xCoordinator zome: remove bytecode from database
                destroy Integrity zome
                Conductor-xIntegrity zome: remove bytecode from database
            end
        end
        Conductor->>Conductor: remove app bundle data from database
        Network-xConductor: ❌ connection attempt fails
    ```
    1. (optional) User specifies network seed/per-DNA properties
    2. New keypair generated
        1. (Optional) registered in DPKI
    3. App installed
    4. Cell(s) marked for immediate instantiation are instantiated
        1. In each cell, `entry_defs`, `link_defs`, and `genesis_self_check` called
        2. Peer communication established, gossip starts, genesis entries published
        3. Cells not totally initialised
    5. `init` lazy-executed on first zome call
    6. During life of app:
        * deferred cells can be activated
        * clones can be made from active or deferred-yet-uninstantiated role
            * network seed (not guaranteed to be unique among all apps using same parent DNA)
            * properties (only useful if clone's functionality should be different, although non-functional modifier can be used to keep network seed same and uniquify clone)
            * origin time (good way of uniquifying clone)
            * quantum time (obscure, don't use for cloning unless you know what it does)
            *     * DNA modifiers
            * (future) DPKI hash
        * Migration considerations
  
        * the client can disable and re-enable cells
    5. End-of-life
        * Cells can be disabled by app's client
        * Cells/app and their data can only be deleted by 'orchestrator' (settle on a name for Launcher, Kangaroo, et al)
            * Can use cell until it's disabled
            * Can participate in network once connected to peers, as long as peers can be contacted -- can be blocked by peers either by warrant or app-level blocking
  

[pdaoust]

This is a huge one but it relieves the burden of work from other pages:

• entries
• links
• zome calls

It needs to be broken up though.

[pdaoust]

Broken up into #494 and #495 (plus #496 re: zome call lifecycle; it really shouldn't be part of this story).

[pdaoust]

Closing now that it's broken into story-sized chunks.