pkg
PACKAGE STATES

:vim set expandtab:

1.  Server states

    We phrase the state machine in terms of a single removal state,
    ABANDONED, which covers both the never-created package instance
    (even with a series of never-finished transaction events).  It may
    be more appropriate to separate the ABANDONED state into
    TX_ABANDONED and PKG_DELETED.

             0
             |
             |
             v
    +--> TRANSACTING --> ABANDONED <--+
    |        |               ^        |
    |        |               |        |
    |        v               |        |
    |    SUBMITTED ----> INCOMPLETE   |
    |        |               |        |
    |        |               |        |
    +--- PUBLISHED <---------+        |
             |                        |
             |                        |
             +------------------------+

    0 -> TRANSACTING
        On initial package creation.

    TRANSACTING -> ABANDONED
        If initial package transaction never committed, commitment
        failed, or explicitly dropped.

    TRANSACTING -> SUBMITTED
        On successful package transaction commitment.  Packages with
        syntax errors or immediate inconsistencies would have failed in
        commitment.

    SUBMITTED:
        The package modified by the transaction is known by a specific
        version.  Its contents are in the repository.

    SUBMITTED -> INCOMPLETE
        If commitment included a deferred inconsistency (package
        dependency is the only expected form), then the package is left
        in the incomplete state.

    INCOMPLETE:
        The package with the specific version string is on the
        incomplete list.  Its contents are in the repository.

    INCOMPLETE -> ABANDONED
        If incomplete package explicitly removed.  (Possibly by
        timeout from arrival in INCOMPLETE.)

    SUBMITTED -> PUBLISHED
        If commitment had no deferred inconsistencies, then the package
        is considered ready for publication.

    INCOMPLETE -> PUBLISHED
        If the deferred inconsistencies, upon reevaluation, are now held
        to no longer be inconsistent, then the package is considered
        ready for publication.

    PUBLISHED:
        The package with the specific version string is present in the
        catalog.  Its contents remain in the repository.

    PUBLISHED -> ABANDONED
        On manual request for package decommissioning, the package will
        be moved to the abandoned state.

    ABANDONED:
        A package with a specific version string is no longer in the
        catalog or on the incomplete list.  Its contents, if they were
        in the repository, should be removed from the repository.

    XXX ARCHIVED might be a special state connected to PUBLISHED, or
    merely a substate.  An archived package has its manifest and
    contents in the repository, but cannot be installed on a client.
    The point of including ARCHIVED packages is to allow client
    deduction on a system not installed by the pkg system.

2.  Client states

            0
            |
            v
        IN_CATALOG ---------> OUT_CATALOG
            |                      ^
    +--->---+---<-------+          |
    |       |           |          |
    |       v           |          |
    |   INSTALLED --> FROZEN       |
    |       |                      |
    |       |                      |
    |       v                      |
    +-- PRESERVED                  |
    |       |                      |
    |       |                      |
    |       v                      |
    +-- DELETED -------------------+


    0 -> IN_CATALOG:
        A catalog update with new entries.

    IN_CATALOG:
        An entry for this package is available in the locally installed
        catalog.

    IN_CATALOG -> OUT_CATALOG:
        Entry formerly present on local catalog is no longer published by any
        repository.  (Package never locally installed.)

    OUT_CATALOG:
        Although a formerly known package, no entry for this package is
        available in the locally installed catalog.  An INSTALLED or
        FROZEN package can never be OUT_CATALOG, as the system will
        preserve the entry until the package is no longer in a locally
        public state.

    IN_CATALOG -> INSTALLED:
        Transition takes place on package installation.

    INSTALLED -> FROZEN:
        Transition takes place if manually frozen or frozen by virtue of
	reference from another package group.

    FROZEN -> INSTALLED:
        Manually unfrozen, or unfrozen by reference drop due to
	change in formerly referring package group.

    INSTALLED -> PRESERVED:
        Old copies moved aside during upgrade of package components, but
	not removed.

    PRESERVED -> DELETED:
        Old copies removed.

    DELETED -> OUT_CATALOG:
	Package has been removed from client catalog.  Client software
	would take a PRESERVED package through DELETED automatically to
	reach OUT_CATALOG.

    PRESERVED -> INSTALLED:
        Package reinstalled or reversed.

    DELETED -> INSTALLED:
        Package reinstalled.

    XXX How does the ZFS snapshot (that we might have taken prior to an
    operation) get represented in the state?  Is there an image state
    machine model as well?

    XXX Need a substate of INSTALLED for damaged packages.

    XXX Need a substate of INSTALLED for packages where the global zone
    portion is available, but local installation has not finished.  Can
    we generalize this state for all diskless installs?