This document is the first introduction for ValOS technicians - the primary infrastructure developers and operators - to the ValOS ecosystem and its infrastructure toolchains and workflows.

This document is part of the vault workspace @valos/kernel (of domain @valos/kernel) which has the description: `ValOS common infrastructure tools and libraries monorepository`.

As a technician you develop and operate the ValOS fabric, the globally distributed web-like infrastructure of servers, services and components which underlies the Valospace.

You use vlm and employ your existing, likely professional knowledge of JavaScript, Node.js, DevOps, backend, library and other software development skills.

You create new open source and/or proprietary node packages. These permanently create new fabric functionalities and expand the Valospace by integrating it to old world systems.

Technician sub-profiles detail the typical stages of software development and operations workflows within ValOS ecosystem. A technician should read the detail docs of their own profiles but also understand the at least the abstract principles of all other profiles, which are expanded below.

This document, like most of the more principled and less pragmatic documents must be understood as strong speculation and as an architectural exercise (although a very serious one) on what-could-be.

This rings especially true for the primary focus of this document, ie. for ValOS Core as the fully functional open source core around which the often proprietary ValOS ecosystem would expand. This is an ambitious, even presumptuous attempt to facilitate the fruitful side-by-side living of open source communities as well as private enterprises as a combination of technical and social architecture.

(The technical part is the ambitious part and the social part is the presumptuous part. :D)

This document has two purposes. Firstly it provides the initial specification of Valaa Open System (ValOS) and secondly it serves as the introduction for Development Operations.

ValOS specification is provided as quoted and numbered ValOS rules.

valos-vault-1.1: ValOS packages are all the npmjs.com packages with @valos scope which don't have cyclic dependencies with other @valos scope packages.

valos-vault-1.2: Valaa Open System (ValOS is defined to be the contents of all ValOS packages and nothing else.

valos-vault-1.3: ValOS specification consists of all files in all ValOS packages whose path in the package matches the JS regex /^specifications\/\w*.md$/ and nothing else.

valos-vault-1.4: Rules in a package are considered to be more specific than the rules in its package dependency tree. More specific rules take precedence.

valos-vault-1.5: All packages which conform to ValOS specification are called ValOS packages. These packages are inclusively considered part of the ValOS ecosystem.

The system is structured into purpose-oriented vertical domains and into four content oriented horizontal utility layers.

Each utility layer is named by the content or service is provides and builds or depends on the previous layers.

• files layer provides files via git repositories.

• packages layer provides npm packages via npm registry. These packages are created by git repositories called vaults.

• authorities layer provides the ValOS live authority service APIs. Authorities are deployed and managed with opspace workspaces.

• chronicles layer provides the resource content as chronicle events and bvobs. These are served via authority service APIs.

TODO(iridian): Figure out and describe the concrete role of domains. NOTE(iridian, 2019-08): Domains are now mostly figured out; they are administrative, organisational units and namespaces.

A DevOp manages these layers by scripts that are delivered inside the packages alongside their main content. A command line tool called ValOS Medium or vlm is used to discover and invoke these scripts as valma commands.

From a DevOps perspective valma, vault and opspace are the three concrete core mechanisms that everything else ties into.

Valma and specific domains are specified in other documents and as such are only briefly described here.

The utility layers are common to everything form the bulk of this document. They are fully specified at the last part of this document after all the brief descriptions.

valos-vault-2.1: A domain is the collection of all the systems, interactions and dynamics which exclusively serve a particular purpose.

valos-vault-2.2: A domain must define the purpose, describe its producers and consumers and should provide a direction for technical and operational structure as well.

For example the @valos/kernel domain provides the essential central ValOS code for developing new ValOS infrastructure software. Its main producers are the kernel software developers and its consumers are the infrastructure software developers. It revolves around developing code as library packages.

valma (vlm in CLI) is a convenience tool for executing command scripts exported by packages in valos workspace contexts. It is a generalization of 'npx -c' behaviour, adding discoverability, ability to invoke global scripts and the ability to invoke multiple scripts at once using glob matching.

valos-vault-3.1: valma is installed with npm install -g valma or as a package dependency

This installs the global CLI command vlm . At its core valma is a command dispatcher to valma scripts in various command pools.

valos-vault-3.2: valma searches the scripts first from the package.json scripts pool, then from ./node_modules/.bin/depends pool and lastly from the OS-specific variant of /usr/binglobal pool.

As an example typing vlm status in some directory context would forward the command to valma.bin/valma-status first if one exists and falling back to the more generic versions if not. The call eventually resolves at the global /usr/bin/valma-status . Its implementation then calls vlm .status/**/* which calls all scripts which match the glob .status/**/* and are visible on the execution context pools (the scripts called by vlm status are known as valma status scripts).

valos-vault-3.3: A package can export valma scripts using npm package.json bin section and by prefixing the exported name with _vlm_ as usual. These scripts will be available for all packages depending on this package in their depends pool.

Running vlm with no arguments lists all available commands grouped by pool in current directory context.

valos-vault-3.5: valma can be used in programmatic contexts to run valma scripts. When done so, valma must be added as a dependency.

This happens just like with the CLI by using vlm <command> [<args>] . ("npx -c" would be the alternative but it's slow and limited).

valos-vault-3.5.1: valma ensures that node environment is loaded

The environment is loaded only once even for recursive script invokations.

valos-vault-3.5.2: valma ensures that 'vlm' is always found in path

This is so that valma scripts can call 'vlm' even valma is not globally installed as long as valma has been installed as a dependency.

valos-vault-3.5.3: valma ensures that the most specific 'vlm' version is used to evaluate a command, preferring scripts over depended over global.

This is so that toolkits can precisely control the whole toolchain in their dependencies.

ValOS has four main utility layers: files, packages, authorities and chronicles. These layers form the core operational infrastructure of ValOS.

It does, indeed (this section pending better understanding on how to write domain specifications).