Explain base:


life-cycle management

A Collection maintains Units of information; Units with various content. These Units do not simply appear and disappear as files in a directory in a directory do: Units have a life-cycle. Units enter their Collection in multiple steps before they become visible. And they may remove themselves with a plan as well.

Unit State mechanics

The Collection (~managing process) will "run" each Unit through some states. It will need to inspect the content of an uploaded Unit to determine its state transitions. Collection owners can influence the state transitions of the Unit via Rules.

Place yourself in the role of the Collection manager. You need to get the Unit in a distributable state (usually Published), and clean it up later. Any single Unit will go through each of the states below, from top to the center. However, many of the intermediate states will probably be passed in one go.

Life-cycle transition diagram
Life-cycle transition diagram per Unit
Does not show states "Incomplete" and "Broken" (yet)

Not all state transitions have equal features; it depends on their purpose. The Collection Rules can be modified by the Collector owners to adjust the behavior per transition. For instance, some rule may put an automatic expiration on any incoming Unit.

Rules may also determine that the Collection managers have to agree on state transitions via the voting mechanism.

TBD: the exact features still need to be designed.

Releasing a new Revision

You may upload a new revision of the Unit. For instance, when you want to set a deprecation of expiration date.

The new Unit will transition step-by-step to reach the same UnitState as the original Unit. When it reaches that state, the original Unit revision will usually be removed (unless you configured to keep historical revisions). Some discovered changes are logged: deprecation, expiration and publication dates, content changes, ownership changes.

The Unit States

(Not to be confused with the United States :-)

The states below are in "natural order", which means that the Collector will default in facilitating transitions from top to bottom. However, this pattern can be influenced in various ways. The usual interference is halting a certain step to be made.

ms:UnitState Purpose and features

This is a condition: there is no Unit with a specific name.


The client would like to upload a certain Unit, of which the payload may still need to be created. At first, the client requests to be allowed to use a certain name.

The reservation request is a partial Unit. It MUST contain owners. It MAY already specify authors, unit-type, size, etcetera. When it contains a payload, it will progress to the Uploaded state.

The Collection Rules may refuse to reserve the name. For instance, some of the provided conditions already fails. Of course, it is better to fail before a large upload than after.

The rules may require a vote from Collection owners to progress, for instance to be able to manually ban unpleasant names before they appear.

The Constitution Rules may specify a relative expire time for the reservation. The Unit must reach Verified State before that moment. The Unit itself may also give an absolute moment of expiration. Whichever comes first will expire the name reservation.


The Unit data is complete, and uploaded in full to the Collector. The client can disconnect: the life-cycle is managed by the Collector as an asynchronous activity. Problems are reported via notifications.

Without explicit name reservation, you can upload some Unit. Of course, all rules which relate to the Reserved state will be applied.


The Collection may want to verify the payload of the Unit. Does it match the unit type? This might be expensive. Clients which use the content SHOULD not trust the content as well, as every good programmer knows.

The server which runs the Collection has hooks which enable you to add your own validator.


The Unit cannot reach a usable state, for some reason, but may stay in the Collection for some time to simplify debugging and repair. The life-cycle log will contain error messages.


The verified Unit is up for voting: do we permit the Unit to be published? The voting rules MAY require confirmation from one or more people from explicit named Identities, the Owners, or Authors. The people which are allowed to vote have access to this Unit to verify it.

The Collection will also check whether all required dependencies are available (at least in 'Verified' state within the same server) before they can be Published all at the same time.

At any time, Units may get set back (from nearly any state) to the Incomplete state when one of the prerequisits disappears.


When Accepted, the Unit may need to wait before it gets Published. Some clients may have access (for instance Collection replicators).


When the publication date has passed (defaults to 'now'), the normal client access rules get into effect. This is the state you expect the Unit to be in for most of its existence.


There is some reason (documented) to use alternatives of this Unit, but not as bad that the Unit becomes deprecated towards end-of-life. This state is meant to offer developments a smooth, long term improvement into something better.

The client is usually not warned when it uses the Unit, but the fresh developer will be informed to search for alternatives.


On a moment of time, which is pre-specified in the Unit, its use MAY get deprecated. This typically comes with some explanation.

The normal access restrictions do still apply. The Client may warn the user actively in (daily) condensed reports.


On an absolute date, which is pre-specified in the Unit, access gets restricted to the Owners of the archive. Clients MAY warn users before expiration.


This payload of the Unit MUST NOT be used anymore. This state will contain a reason for this action, for instance triggered by legal take-down requests. This state is more serious than removal of the Unit: it reflects the instruction to clients to return to a situation as if this Unit had never existed immediately.


The Unit itself does not exist anymore, and cannot be recreated until an provided absolute date or relative time span in the Rules.

Owners of a Collection are able to push any Unit into Expired, Withdrawn, Blocked, or Free state.


The name of the Unit is reusable for an unrelated Unit.

mark@overmeer.net      Web-pages generated on 2023-12-19