The make-up of the platform

How the platform is made: the kernel and the functions, the layers, the life cycle of an instance, the channels between the parts, storage and journals, where what lies in the sources.

1 General information

1.1 Designation and name

The O.G.A.S. platform of personal programs (ОГАС).

1.2 Software needed to run

The platform works in Ubuntu inside WSL2 on Windows 11; the workshop is a Windows program on the system WebView2 (see section 4). The order of installing and the make-up of the delivery — Building, installing and maintenance.

1.3 Programming languages

The kernel and the functions of the platform are written in Rust, the common code of modules (OGAS SDK) in Python and Rust, the page of the workshop in HTML, CSS and JavaScript without a bundler.

2 Functional purpose

The platform lets a person build personal programs of nodes, modules and a pulpit without programming, and use them. What it does for this is described by Getting started and The workshop.

3 Description of the logical structure

3.1 Layers

3.1.1 The platform consists of four layers; each layer works in OS processes of its own (table 1).

Table 1 — Layers

flowchart TD
    user[Person] --> window[Workshop in Windows]
    window -->|127.0.0.1, token| ui[Function ui]
    ui --> core[Kernel]
    graph[Function graph] --> core
    canvas[Function canvas] --> core
    settings[Function settings] --> core
    modules[Function modules] --> core
    observe[Function observe] --> core
    i18n[Function i18n] --> core
    sources[Function sources] --> core
    assistant[Function assistant] --> core
    programs[Person's programs] -->|127.0.0.1, key| gate[Function gate]
    gate --> core
    core --> module[Module]

3.1.2 Functions do not connect to each other directly: all messages go through the kernel. The structure of the source texts — Appendix A.

3.2 Constant rules of the make-up

The rules of the make-up are required for all parts of the platform and show how the rules of development (Rules of development) apply to this platform:

1) the kernel holds no subject logic, no nodes of the graph, no interface, no code of modules and no knowledge of the functions of the platform (rule 2.6); 2) a function is an OS process of its own; functions do not link each other's code and interact only through the kernel (rule 2.3); 3) a module does not know the make-up of the platform and other modules: everything needed to build it in it declares in its manifest (rule 2.3); 4) data are passed through named ports and packets, not through hidden shared state (rule 2.7); 5) a command changes the state, a query only reads, an event tells of what happened (rule 2.7); 6) an error holds a code, a category, a place and a sign whether a retry is allowed (rule 3.2); 7) the failure of one OS process does not stop the others, if they can work without it (rule 2.3); 8) documents are kept in files and are written whole or not at all; each data folder is written by its owner (3.8.1, rules 2.4 and 3.5); 9) the workshop can be replaced without changing the kernel (rule 2.3); 10) a new direct Rust dependency is written with its reason in 3.9 (rule 2.8); 11) the limits of the kernel are the settings core.*; protocol quantities (the JSON-RPC version, the line limit of 4 MiB) are constants of the contract in core/protocol (rule 2.2).

3.3 The kernel

3.3.1 The kernel is one long-living OS process. The kernel:

• makes the data folder and the lock of the instance;
• reads the register of functions and the description of each of them; there is no knowledge of functions in the code of the kernel;
• starts the functions, watches and restarts them; starts modules at the request of a function with the right process;
• takes connections on a Unix socket and passes on commands, queries and events;
• reads and writes documents whole (the file service);
• limits the size of messages, the queues and waiting time by the settings core.*;
• gives out identifiers, writes the start journal boot.jsonl and the kernel journal core.jsonl;
• reports the fall, unavailability and recovery of functions so that it is seen what broke and where.

3.3.2 The kernel knows the protocol, the identifiers, the life cycle, the limits, the common wrapper of a document and the declared rights of functions. The meaning of modules and data is unknown to the kernel. The kernel does not start the Python interpreter itself and does not put in Python variables.

3.3.3 The order of choosing the receiver of a message:

the method begins with "core."  → handled by the kernel
otherwise                       → the owner of the method from the handshake (commands, queries)
  no owner                      → method_not_found
  the owner is unavailable      → function_unavailable
  otherwise                     → pass the request on, return the answer to the sender

3.3.4 A function cannot declare a method with the prefix core.. Any other method belongs to exactly one function.

3.4 The functions of the platform

Table 2 — The functions of the platform

At introduction each function declares its commands, queries, events and dictionary folders, and then registers the schema of its settings at the function of settings — and again each time that one comes up anew (Settings, section 3). The kernel passes messages on by the declared list without knowing their meaning. Adding or replacing a function is putting its folder with its description and its executable file and changing the entry in the register; the kernel is not rebuilt for it.

3.4.1 The register of functions and the description of a function

The register data/functions.json holds what the instance decides: id, the path to the executable file, enabled, capabilities. The description functions/<id>/function.json in the folder of the function holds what is known of the function itself: requires, optional, platform.min / max, contract, restart, interactive. The formats of both — File formats, section 3. The kernel joins them by id when the instance starts; a function whose description cannot be read it does not start (function_description_invalid), the others work.

• requires — the functions this one depends on: all functions whose contract it uses (Rules of development, 2.3.3). A function is started only after all its dependencies except the optional ones have passed the handshake. A closed circle of dependencies is an error of setting up the register.
• optional — those of requires without which the function works: it uses their contract while they are available, and without them goes on working and says what is missing (rule 2.3.4). That an optional dependency is not there, the function learns from a refusal to a call of its method: method_not_found — nobody declared the method, function_unavailable — its owner does not work; in the common code this is request_optional. An optional dependency does not set the order of starting and does not enter a closed circle; its failure does not stop the dependent function. A name in optional that is not in requires makes the description invalid.
• If a function has spent its restarts, the kernel does not stop; the functions for which it is not named in optional are stopped and not restarted.
• interactive: true — the function needs the workshop. Such functions are started by the verbs start and ui; the verbs described in the register do not start them.
• restart: false — after it ends the function is not restarted.
• capabilities — the rights a function may ask for at introduction. The right process is given only to the function of modules.
• The path to the executable file is counted from the installation folder. If the file is not there, the kernel looks for a file with the same name beside itself. This search is meant for development and does not replace a right path in the delivery.
• The verbs of the command line other than the verbs of the kernel, their calls and arguments are written in the register (the field cli), not in the code of the kernel (section 5).

A damaged or missing register does not stop the kernel: the kernel works without functions and refuses the commands that need the register.

3.4.2 Introduction and the health check

The first message of a function is function.handshake: the id and version, the supported versions of the contract (contracts.core is required), the commands, queries, events, rights, dictionary folders and the names of surfaces — the last are needed only for diagnostics (The workshop, section 8). If the first message is another, the connection is closed. The one-time launch token is removed after the introduction and is not taken again. The whole message — Exchange with the kernel, section 4.

After the introduction the kernel asks the function function.health every core.health_interval_ms. With no answer within core.health_timeout_ms the function becomes degraded: the kernel stops it, and it goes on by the same path as a fallen one — it spends one restart attempt (3.6.4). With the reverse query core.health a function checks that the kernel itself works.

3.5 The division of ownership

• the kernel — the life cycle of OS processes, the socket, paths, writing documents whole;
• the function of the graph — the graph, the programs that are on and their variables, events, the plan of carrying out, the state of shared objects, checkpoints, past runs and their clearing;
• the function canvas — the document of the pulpit;
• the function of the profile — the computer key and the letter key of the profile, one's sendings and letters; it keeps no main key, and writes a key file only where the person said;
• the function of modules — manifests, environments, the meaning of process_handle, which modules are up and which to unload so that there is enough video memory, the work folders and result files of runs;
• the function of settings — the values of all levels and the schemas;
• the function observe — the journal of events and the list of problems;
• the workshop — the window, input, focus, the layout of windows and a copy of the last state received;
• a module — its own applied work and its outside actions.

JSON documents are written by functions only through the file service of the kernel and only their own. Folders with files (the Python environment, the work folder of a run, copies of modules for an export, journals, the memory of a node, result files) the owner writes itself and only in its own folder (3.8.1).

3.6 The life cycle of an instance

3.6.1 Start

1. The kernel makes the folders run, logs and config in the data folder. The other folders are made by their owners when they need them.
2. It reads the limits core.* from config/core.json, then from config/system.json. If there is no core.json, the kernel writes it empty: the defaults stay in the schema. If a file cannot be parsed, the start refuses with the name of the file and the line number.
3. It writes the beginning of the start into logs/boot.jsonl.
4. It takes the lock ogas.lock: writes the pid, the start time and a random mark into it and holds a flock on the file. The lock is taken — see 3.6.3, «A repeated start».
5. It makes a Unix socket with mode 0600. The path is run/ogas.sock if the folder lies on a Linux file system (not 9p, DrvFs, NFS, CIFS) and the path fits into 107 bytes. Otherwise — XDG_RUNTIME_DIR or /tmp with the same conditions. If no variant fits, the start refuses. The functions get the true path in OGAS_SOCKET.
6. It checks the dependencies of the functions.
7. It starts the functions in the order of dependencies with the environment of 3.7.4.
8. It waits for the handshake of each function with a time limit. A dependent function does not start before its dependencies.
9. It reports readiness — full, or partial if some functions are unavailable.

A failure of a function does not stop the kernel. If function A depends on function B, and B did not start, did not pass the introduction or spent its restarts, A is not started (or is stopped) and is marked unavailable. An optional dependency (3.4.1) does not cause this.

3.6.2 Stop

The kernel stops taking new starts, publishes system.stopping, waits for the OS processes born by the functions to end within core.process_stop_grace_ms and forces the remaining ones to end. Then the kernel closes the channels of the functions: a function reads to the end what came to it — system.stopping among it — and ends itself, so what it does on a stop gets done: the graph stops runs, the function ui passes the event to the window, and the window closes. A function that did not end by the end of core.shutdown_grace_ms the kernel ends by force. The lock is taken off at exit.

On leaving the workshop the function ui sends core.shutdown, and the instance stops; closing the window only hides it at the icon by the clock (The workshop, 2.1). A failure of the function ui or of the window does not stop the instance; restart: false only forbids a restart.

3.6.3 Recovery

A failed function gets a limited number of restarts in a row — core.function_restart_max — with a growing pause: the first core.function_restart_base_ms, each next one twice as long. A successful handshake resets the counter. After the attempts are spent, the function is switched off until the next start of the kernel. An unfinished command to it gets function_lost; only commands that are safe to carry out again are repeated automatically.

The lock is a flock(LOCK_EX) on the open ogas.lock. An OS process that ended without taking the lock off frees it when the system closes the file. The JSON inside the file holds information for diagnostics and is not the lock. Two starts at once will not both get the lock.

After a function ends, the kernel removes the record of its OS process, so that a function that ended is not shown as working.

A repeated start. After a failure of the workshop the instance goes on working without a window, and the person starts the shortcut again. A repeated start does not end in a refusal at the lock but wakes the working instance:

1. The verb start or ui did not get the lock. It takes the pid from ogas.lock, checks by /proc/<pid>/exe that it is the same program, and sends it the signal SIGUSR1. The verb itself prints «already running» and ends with code 0.
2. The kernel sends all functions the event system.activate and starts anew each function with interactive: true that does not work. The kernel chooses the functions by the sign interactive from their descriptions.
3. The window function, having got system.activate, opens the window if there is none: the window is not connected and its OS process does not work. A working or starting window is not opened again; the event reaches the window page, and a window hidden by the clock is shown.
4. A verb of the register that needs the workshop (5.3), with the lock taken, does not end in a refusal like the other verbs of the register, but leaves the working instance a note — the verb and the values of its arguments (run/launch.json, File formats, section 3) — and sends the same signal. The woken instance takes the note and carries out the calls of the verb itself, if its register describes this verb as needing the workshop and takes its arguments. A refusal is written into the kernel journal, the instance goes on working. A note is read once; an unreadable one, one of another format or one that lay longer than half a minute does not count as a request, and an instance that is starting does not take a note of an earlier one.

The window function does not restart a failed window: a window failing at its start would be restarted endlessly. The window opens again at the person's request. The verbs described in the register end in a refusal at a taken lock: they would do work the working instance does not know of.

3.6.4 The states of a function

stateDiagram-v2
    [*] --> Discovered
    Discovered --> Starting
    Starting --> Handshake
    Starting --> Failed
    Handshake --> Ready
    Handshake --> Failed
    Ready --> Degraded
    Ready --> Restarting
    Ready --> Stopping
    Degraded --> Restarting
    Degraded --> Stopping
    Restarting --> Starting
    Restarting --> Failed
    Failed --> [*]
    Stopping --> [*]

Discovered — found in the register and waiting its turn: a function is started after those it does not work without; Starting — the OS process is being started; Handshake — the process is started, the first message is awaited; Ready — working; Degraded — did not answer the health check, the kernel stops it; Restarting — ended itself or was stopped for silence and waits for the pause before a restart; Failed — does not work, and the kernel no longer starts it: did not start, did not introduce itself in time, spent its restarts, was left without a required dependency or ended without the right to a restart; Stopping — the instance is stopping. In core.status the states are called by the same words in small letters (discovered, starting, handshake, ready, degraded, restarting, failed, stopping), their texts are core.state.<state> in the dictionary of the kernel.

3.6.5 The states of a module

stateDiagram-v2
    [*] --> Missing
    Missing --> Invalid
    Missing --> NeedsEnvironment
    NeedsEnvironment --> Stopped
    Stopped --> Starting
    Starting --> Ready
    Starting --> Crashed
    Ready --> Executing
    Executing --> Ready
    Executing --> Crashed
    Crashed --> Restarting
    Restarting --> Starting
    Ready --> Stopping
    Stopping --> Stopped

Missing — there is no module, Invalid — a manifest with errors, NeedsEnvironment — an environment is needed, Stopped — ready to start, Starting — started and waiting for init, Ready — ready to work, Executing — carrying out a step, Crashed — ended with a failure, Restarting — being started again, Stopping — stopping.

3.7 Channels

3.7.1 Function — kernel

A Unix socket, one connection per function. Reading and writing go in different threads, messages are JSON-RPC 2.0, one per line, the queues are bounded, the mode of the socket is 0600. That it is truly the function the kernel started is confirmed by the one-time launch token and by SO_PEERCRED: the uid of the instance and the pid of the born OS process. The rules of a line and of the wrapper of a message — Exchange with the kernel, sections 2, 3.

The term of an answer is set only by whoever asks. The kernel, the function ui and the window program are intermediaries: a call they pass to the owner of a method they wait for as long as the owner needs, and set no term of their own. Otherwise an intermediary would break off work the owner does within its own term, for example a step of a module whose manifest allowed ten minutes. A call does not wait for an answer endlessly: when the owner of a method disconnects or fails, all its calls without an answer get function_lost at once; when the asker disconnects, the answer is not passed to it. How many calls one function may keep waiting at once is limited by core.rpc_queue; beyond that — the refusal backpressure.

3.7.2 The channel of a module through the kernel

graph   → kernel → modules : module.execute
modules → kernel           : core.process.spawn, core.process.stdin.write
kernel  → module stdin     : the JSON-RPC messages of the module as lines
module stdout / stderr → kernel → event process.io.chunk → modules

sequenceDiagram
    participant G as graph
    participant C as kernel
    participant M as modules
    participant P as module
    G->>C: module.execute
    C->>M: module.execute
    M->>C: core.process.spawn
    C->>P: OS process
    M->>C: core.process.stdin.write
    C->>P: JSON line into stdin
    P-->>C: stdout bytes
    C-->>M: event process.io.chunk
    M-->>C: result
    C-->>G: execute answer

The kernel checks only its own wrapper and does not parse the JSON-RPC inside the stdout of a module: the lines are put together and parsed by the function of modules. The stdout of a module belongs to the protocol, diagnostics go to stderr. When both streams are closed, the kernel sends process.io.closed with the exit code. The events process.io.* are got only by the function that started this OS process.

3.7.3 The workshop — the function ui

TCP on 127.0.0.1, one window at a time, the same JSON-RPC 2.0 by lines with a line limit of 4 MiB. The function ui starts the window program and passes it the port and the session token. The first message of the window is ui.window.hello with the token. The requests of the window the function ui passes to the kernel through its own connection; of the kernel methods only core.status, core.health, core.event.subscribe and core.shutdown are available to the window. The events of the kernel come to the window as the notification event. Threats and protection — Protection, 3.10.

sequenceDiagram
    participant W as Workshop (Windows)
    participant U as ui (WSL)
    participant C as Kernel
    U->>W: start: --port, --token
    W->>U: ui.window.hello {token}
    U-->>W: {status: ready}
    W->>U: process.run.start
    U->>C: process.run.start
    C-->>U: answer
    U-->>W: answer
    C->>U: event run.changed
    U-->>W: event run.changed

If the window missed events or reconnected, it asks for the whole state anew.

3.7.4 The launch environment of a function

The kernel starts a function with an empty environment and passes only:

Table 3 — The launch environment of a function

The function ui gets the same environment; it does not need the Linux display variables. The stdin stream of a function is /dev/null; stdout is inherited from the kernel; stderr the kernel catches and writes into its journal (3.8.2); the protocol goes only through the socket.

3.7.5 The launch environment of a module

The kernel starts a module with an empty environment and adds PATH, LANG / LC_ALL and the variables from the field env of the request core.process.spawn. The function of modules itself passes PYTHONUNBUFFERED=1, PYTHONPATH, HOME, the proxy variables if they are set (3.7.4), OGAS_MODULE_ID, OGAS_MODULE_VERSION, OGAS_MODULE_DIR and, except for a service, OGAS_RUN_DIR; the paths to the neural networks the parameters of a node chose come not in the environment but with the step (Modules, section 11). The memory folder of a node comes not in the environment but with each step: a module is one for all its nodes, and each node has its own memory (Modules, section 4). A module does not get OGAS_LAUNCH_TOKEN and OGAS_SOCKET and does not connect to the bus. The programs the parts ask to start the kernel starts from one thread of its own that lives as long as the kernel, and each gets SIGKILL when the kernel ends, a crash included: a module in the middle of a long step does not hold the video card after the kernel.

3.8 Storage and observation

3.8.1 The data folder

Everything that belongs to a working process lies in its one folder processes/<id>/: documents, runs and their results, files the person gave it, the memory of its nodes and the Python environment. A deleted folder takes the process away whole, and nothing of it stays elsewhere. A run is named by the local date and time of its start — 2026-10-08_07-29-12, on a clash in the same second -2, -3 — and the person finds its results in results/ by date. The folder of a process is named by its identifier; renaming the process does not change the folder: calls and paths refer to it.

Table 4 — The data folder

There is no database. The file service of the kernel writes a document whole: a temporary file, fsync, the former file is renamed to .bak, the temporary one takes its place, fsync of the folder. The set of files of a process has a generation number; after a failure only a complete generation is taken. The formats — File formats.

3.8.2 The division of observation

• The kernel observes itself and the functions: health, restarts, handshake errors, queues, writing documents. The journal logs/core.jsonl, the state snapshot core.status. The output of a function to stderr the kernel writes into this journal line by line with the name of the function (function.stderr) and repeats it into its own stderr: a function started from a shortcut has no terminal, and without this its last message (a refusal at its start, a failure that could not be published) would be lost. A service thread of the kernel that did not start also leaves a record (core.thread_failed). A record with the code of its cause is also left by each refusal after which nothing of a function may remain: a connection that did not pass the introduction (function.handshake_failed), a refusal of the peer check and a connection beyond core.connections_max (connection.refused; beyond the limit — one record while it holds, so that a knocking program does not fill the journal), a function the kernel no longer starts or restarts.
• Each function reports a failure of its background work with the event function.work_failed (Exchange with the kernel, section 7).
• The function of modules observes modules: the start, the output streams, the environment, the manifest.
• The function observe gathers the common stream of events and the list of problems for the workshop.

Journals are written in the JSON Lines format:

• boot.jsonl and core.jsonl — the kernel, also before the function of observation starts;
• logs/events-<YYYY-MM>.jsonl — the common journal of the function observe, by months, by the time of writing; logs/events.jsonl, if there is one, is read as the oldest part;
• runs/<run_id>/events.jsonl — the journal of a run, if the run_id fits as a folder name.

The events the kernel sent out before the function of observation connected — for example, that a function was not started without its dependency — it takes at its start from the memory of the latest events of the kernel (core.event.subscribe), beginning after the last event of this instance in its journal: no refusal stays without a record and a problem, and no event is written twice.

Journals are not shortened: what is written stays. The journal of a run is deleted only together with the run, by the rule graph.runs_keep (The program: graph and runs, section 12). Old months of the common journal are deleted only by a command of the person — observe.logs.remove, «Remove the months before» in the window of the platform journal — or by the setting observe.logs_keep_months, by default — keep everything (Settings, section 8); the current month is never deleted. The deletion is written into the journal with the event logs.removed; a search reads the journal from the newest month back until it has gathered what it needs.

One record of a journal goes to disk in one write call, so the records of different threads do not mix. If an earlier start was broken off in the middle of a write and the file does not end with a line break, the next record first adds the line break: a broken line stays one spoiled line and does not spoil the next. Readers skip a line they could not parse.

A record of the kernel journal holds time, source (core or the id of a function), event, error_code on an error and a short message. By the record the place and cause of a failure are found without reading the source texts.

A restart of a function is shown by the event function.restarted with the number of the attempt and the pause; after the attempts are spent — by the event function.failed with the code function_restart_exhausted.

The function of the graph publishes node.changed for module nodes: queued when a step waits its turn at the module, running when the module took it, and completed, failed or cancelled (the step was broken off by a stop) after. Nodes of the platform (condition, merge, loop) do not publish such events, since they call no module and fire at once. The exception is the nodes a branch stands on: a question, waiting for a signal, a pause. About them the function of the graph publishes waiting when the branch stood still, and completed or cancelled when it went on or the wait was taken off — after this is written into the checkpoint: otherwise nobody would know that the run stands exactly here.

Events have the number event_id, which only grows, though not necessarily by one: a number is also given to an event sent to one function (process.io.*), which does not get into the memory of the kernel or to the others. A subscriber passes the last number it got, whatever the step before it; if there is no such number in the memory of the kernel any more (its size is core.event_ring_size), the answer says resync_required, and the subscriber reads the whole state anew. The format of the journals is not made compatible with OpenTelemetry.

3.9 Threads and dependencies

The kernel uses standard Rust threads, without Tokio: a thread taking connections, a reading thread for each connection, a separate thread for handling each request of a function (at once no more than core.rpc_queue per connection, beyond that — the refusal backpressure), a thread watching each born OS process and threads reading the stdout and stderr of modules. Writes into one connection go under a lock. For an instance of one person this is enough.

A lock is held only for the time of reaching the guarded data. It is not allowed to take a second lock without letting go of the first. The only departure is the video memory gate of the function of modules: under it room on the video card is freed and taken with other locks taken, and the gate itself is never taken under another lock, so a deadlock is ruled out.

The direct Rust dependencies and what they are for:

• the kernel and the functions: serde, serde_json — reading and writing JSON;
• the kernel in addition: libc — SO_PEERCRED, pidfd, flock, signals and the file system type of the socket;
• the function of the graph in addition: libc — the local time offset (localtime_r) for events by the clock;
• the function ui: only serde_json and ogas-protocol;
• the function of the profile in addition: ed25519-dalek — signing parcels; crypto_box — letters sealed for the profile, as the side of the site seals them (libsodium); sha2 — the counting task: millions of SHA-256 in seconds; argon2, chacha20poly1305 — the password of a key file; getrandom — the randomness of the system for keys; cryptography written here would be a risk nobody should take;
• the common protocol code under Unix and the sources function: ed25519-dalek — the check of the signature of the site ogas.space; a signature written here would be a risk nobody should take;
• the workshop (a separate set of Cargo packages for Windows, the target x86_64-pc-windows-msvc): tauri 2, tauri-build, serde_json; the window page — without outside JS libraries.

The Cargo packages of the main set: ogas-protocol, ogas-core, ogas-graph, ogas-modules, ogas-settings, ogas-observe, ogas-i18n, ogas-canvas, ogas-sources, ogas-profile, ogas-ui, ogas-gate, ogas-assistant, ogas-module — the SDK for modules in Rust. A separate set — ogas-window in functions/ui/window. The exact versions of all dependencies are pinned by Cargo.lock.

4 Technical means used

• The kernel, the functions, the modules and the data work in Ubuntu inside WSL2.
• The workshop is the Windows 11 program ogas-window.exe on Tauri 2 and the system WebView2. It is started by the function ui through the WSL mechanism that lets Windows programs be started from Linux (interop).
• Without such a mechanism (for example, in ordinary Linux) the platform works without the workshop, through the command line.
• The socket of the kernel lies only on a Linux file system, not on Windows disks.
• The Windows disks are seen in WSL as /mnt/<disk>, unless /etc/wsl.conf sets another root; the function ui learns the root from wslpath. They are within reach of a module, but work noticeably slower than the Linux disk.

5 Calling and loading

5.1 One program ogas-core holds the kernel and its command line verbs:

ogas-core start   [--data-dir PATH]
ogas-core ui      [--data-dir PATH]
ogas-core doctor  [--data-dir PATH]
ogas-core <a verb from the register> [--<argument> VALUE …] [--data-dir PATH]

5.2 The verbs of the kernel:

• start starts the functions by the register, including the functions with the sign interactive if their entry is enabled. An ordinary start with the workshop is ./ogas or ogas-core start;
• ui starts the functions with the sign interactive even if their entry is disabled;
• doctor prints the kernel's own signs — what each of them means is said in Building, installing and maintenance, 4.1; with no register or no fitting socket path it ends with code 1. Then it carries out the environment checks the functions of the register declared in their descriptions (File formats, section 3), without knowing their meaning, and for each prints a line <function>.<check>=passed or =failed with the text from the dictionary of the function — in the language of the system (LC_ALL, LC_MESSAGES, LANG), and if the function has no such dictionary, in English. The outcomes of the checks of the functions do not change the exit code. doctor only reads files; it starts only the programs the checks of the functions name, and waits for each no longer than the inner term of the kernel. doctor does not look for the Python interpreter: choosing the interpreter belongs to the function of modules (the setting modules.python_candidates). Which checks the delivery declares — there too, in Building, installing and maintenance, 4.1.
• backup makes a backup of what the platform does not make again and takes away the copies past the number kept (Building, installing and maintenance, 5.6); it works while the platform is stopped too;
• stop asks the running instance to stop as on leaving the window and waits until it ends; when none runs, it says so;

5.3 The other verbs are described in the register of functions (the field cli, File formats, section 3): the name of the verb, the preliminary calls, the called method, waiting for the outcome and the arguments with their signs of being required and their defaults. The kernel parses the arguments by this description and puts their values into the call without knowing their meaning. Without a required argument the verb ends with code 1 without starting the instance. Refused the same way, without starting the instance, are a verb that is neither the kernel's nor in the register, a flag that is not among the arguments of the verb, a flag without a value, a repeated flag and a second word instead of a flag; the verbs of the kernel take no flags except --data-dir (Rules of development, 3.2.2). On an undeclared method or an error of the call a message is printed and code 1 returned. The flag --help prints the verbs of the kernel and the verbs of the register of the data folder with their arguments. The verbs set no term of their own: they wait for the outcome however long installing or a run lasts; waiting is broken off with the keys Ctrl+C.

A verb of the register starts the instance without the workshop and stops it after its call. A verb with the sign interactive — «needs the workshop» — starts the instance together with the workshop, like start, and does not stop the instance after its calls; a refusal of its call at the start ends the start with code 1. If the instance is already working, the calls of such a verb are carried out by it (3.6.3). What exactly the workshop opens by such a verb the kernel does not know: it knows only the description of the call.

5.4 The register of the delivery describes the verbs of running a process without the workshop, installing the environment of a process and starting a program with its face (Building, installing and maintenance, 5.2).

5.5 The kernel holds no knowledge of the functions (Rules of development, 2.6). ./ogas is a wrapper over ogas-core (Getting started, 2.2).

6 Input and output data

The formats of the documents the platform reads and writes — File formats. The messages between the parts of the platform — Exchange with the kernel.

Appendix A (informative). The structure of the source texts

The appendix says where to put new files. The structure of the source texts follows rules 2.1 and 2.2 (Rules of development):

• each part has a main file — the entry point; it starts the part and passes the work to the files of tasks, and does not do it itself;
• one task — one file; a task with subtasks — a folder with its own main file;
• a file is split when a second task appears in it, not because it is long;
• the settings of a part are described in its schema file settings.schema.json, texts for the person in its locales/ru.json and locales/en.json, error codes in its codes.rs, the other constants of the contract and inner quantities in its constants file constants.rs. Code takes the values from there and keeps no copies of its own.

A.1 The repository tree

repository
  README.md                the face of the repository: what it is and how to start it
  LICENSE, NOTICE          the licence of the platform; what is under which licence, the name and the mark
  CONTRIBUTING.md          on what terms an outside change is taken
  docs/                    the documentation; not part of the platform
    README.md              the map of the documentation: which documents there are and whom they are for
    guide/                 for whoever builds programs: getting started, the workshop
    reference/             reference: kinds of nodes, formats, settings, error codes, terms
    sdk/                   OGAS SDK: the guide for the author of modules and scripts
    platform/              make-up, program, modules, protection, building, rules
    contract/              contracts: exchange with the kernel and the methods of functions
    en/                    the English translation with the same layout and its own map
  core/protocol            the common code of the exchange: JSON-RPC 2.0, JSON Lines, errors, identifiers
  core/kernel              the kernel: the loop, passing messages on, the lock of the instance
  core/data                the data of the development instance: the register and the settings of the delivery; processes and personal things of the person are not in git
  functions/<id>           a function of the platform — a separate OS process
  modules/<id>             a module of the person — a separate OS process; the platform puts no modules of its own here
  sdk                      OGAS SDK: the common code of modules in Python and Rust, its checks and test modules
  scripts/                 building the delivery, the list of outside licences, measurements and the check of the rules with its own checks;
  installer/               the installer of Windows: the NSIS script, `setup.sh` — what it does inside Linux, its texts in both languages
                           the checks of the rules themselves are in scripts/rules/, a file per group of rules
  assets/                  the mark for the shortcut
  work file/               mock-ups of the workshop
  .github/workflows/       CI: runs `make ci`

Documents lie only in docs/; their make-up is the map of the documentation. The root holds the working files of the repository, not documents of the product: README.md, the licence LICENSE and the information NOTICE about what is under which licence, the terms of an outside change CONTRIBUTING.md, Makefile, the start ogas, ogas.cmd and the shortcut ogas.desktop, the Rust build files and the Rust version rust-toolchain.toml, the editor workspace Concept.code-workspace. The checks of the common code of modules are in sdk/tests/, the test modules they run on are beside, in tests/doubles/: an element comes and goes together with its checks (rule 2.10). An author checks their module without the platform with the SDK helper sdk/python/ogas_check.py and keeps such checks in the module folder (test_<id>.py); make ci checks the platform, not the person's modules.

A.2 The kernel — core/kernel/

The kernel holds only what the platform rests on. A new function is added by an entry in the register, not by a file in the kernel.

core/kernel/
  settings.schema.json   the schema of the keys core.*: defaults and allowed values
  locales/{ru,en}.json   the names and hints of the keys core.* for the person
  src/
    main.rs              the entry point: parsing the command line, signals, choosing the verb
    codes.rs             the error codes of the kernel
    constants.rs         the inner quantities of the kernel and the terms that are not set up

Table A.1 — The kernel — core/kernel/

The end-to-end checks are in core/kernel/tests/: hostile.rs (spoiled registers, the lock, a refused handshake), transfer.rs (export and adding of a process), runs.rs (keeping runs), wake.rs (a repeated start), cli.rs (the command line verbs on processes from fixtures/processes/), latency.rs (measuring the latency, run by hand), common/ (the common frame of these checks), fixtures/ (test functions in Python).

The functions are started by lifecycle.rs, modules by process.rs at the request of a function with the right process.

The kernel starts before the function of settings, so it reads the keys core.* itself — by its own schema and its own files of levels.

A.3 A function of the platform — functions/<id>/

All functions are made the same way:

functions/<id>/
  Cargo.toml
  function.json          what the function is: dependencies, contract, window, restart (File formats, section 3)
  settings.schema.json   the settings schema of the function, if it has any: keys, defaults, allowed values
  locales/{ru,en}.json   texts for the person: names and hints of settings, errors, labels
  src/
    main.rs              the entry point: `start_function` — start and introduction to the kernel, the table «method → file of the task»
    state.rs             the state of the service: what the function keeps in memory while it works
    codes.rs             the error codes of the function
    constants.rs         the formats of documents and the inner quantities of the function
    <task>.rs            one task — one file
    <task>/              a task with subtasks — a folder: mod.rs and a file per subtask

Table A.2 — A function of the platform — functions/<id>/

A new command is a row in the table of methods of main.rs and a function in the file of its task, not a new code package. A new file appears when the function gets a new task.

The common code is in core/protocol, a file per task; lib.rs only lists them:

• frame.rs — JSON Lines lines and writing a journal in whole records;
• layout.rs — where what lies in the process folder: runs, results, the memory of nodes; the name of a run by local time;
• media.rs — the kind of a file by the ending of its name: modules name their files by it, and the graph the result files;
• message.rs — a JSON-RPC message, an error, fields;
• client.rs — the client of a function: the connection to the kernel, the introduction, the loop of methods; Unix only;
• registry.rs — the register of functions and the description of a function;
• time.rs — time in documents;
• constants.rs — the constants of the contract of the platform, among them the categories of refusals, and the inner waiting terms common to all parts;
• codes.rs — the common error codes and their categories;
• report.rs — what a function says itself: a published event and a failure of background work nobody waits for;
• contracts/<owner>/ — the constants and codes of the contract of an owner that dependent parts name too: codes.rs, constants.rs;
• settings.rs — the settings schema and the reading helper that takes a fallback default from the schema of the owner (rule 2.2);
• site.rs — the keys of the site ogas.space and the check of the signature of its files; Unix only;
• web.rs — going to the network with the system program curl: GET and POST, https only; Unix only.

The window program links the same code, except the Unix parts — so the line limit and other constants of the window are the same as everyone's.

A.4 The workshop — functions/ui

The function ui works in WSL, the window program in Windows. The make-up of the window — The workshop, section 4.

functions/ui/
  src/           the function ui (Linux): main, relay, launch, face, layout, library, locales, font, settings
  window/        the window program (Windows, Tauri 2): its own set of Cargo packages, the target x86_64-pc-windows-msvc
    src/         main.rs — the Windows window and the commands of the page; link.rs — the link with the function ui: calls
                 waiting for an answer, the state of the link; connect.rs — connecting and the introduction, reading answers and events, the end of the link
    tauri.conf.json, capabilities/, icons/
    cdp.py       checking the page from WSL with the WebView2 debugging tools (for development only)
    ui/          the page built into the executable file
      index.html, style.css, app.js   the entry into the page: ties the parts together
      start.js     starting the page when there is a link: the look, the data of the platform, events, deferred settings
      desk.js      redrawing: the look and the note about the link, the layout after measuring the host, windows
      keys.js      the keyboard of the page
      shell.js     areas: the brand, the strip on top, the bars along the edges, the host; windows and dragging
      faces.js     common forms: a bar in three states, the tab of a window
      windows.js   windows on the host: size, drawing to edges, maximizing, folding
      events.js    events of the platform → state; missed events → a request of the whole state
      lib/         dom (updating the page), rpc (requests), look (`ui.*` → CSS), glyphs (icons), labels (texts), font,
                   units (sizes in words)
      state/       the common state of the workshop — what several windows read or do, a file per task: session,
                   documents (the documents of a process being edited and steps back), process (the open process: documents from
                   the owners, the program, what is saved, the check), processes (going to another process, making, importing and exporting),
                   pulpit (the strip of the pulpit and its slots), run (the program at work), overlay (the state of a run), settings,
                   modules (the catalogue of modules), workspace (the data of the platform around the process), parts (which parts
                   of the platform do not work and why), layout
      host/        the windows on the host; each is a folder of its own (rule 2.10): index.js — the description of the window (name, sign, bar,
                   the parts of the platform the window shows, its own session fields, hooks),
                   view.js — the view, state.js — what only this window does, locales/ — the words only it says,
                   style.css — its own look, tests.js — its own checks;
                   index.js — the only list of windows; frame.js — the body of a window by The workshop, 5.1; controls.js — what several windows show;
                   windows — a folder per window, their list is host/index.js, their make-up is The workshop, table 1
      tests/       checks of the common state and the frame and their fixtures (fixtures.js); run.js runs them and the checks of the windows; all — in the WebView2 of the window
      fonts/       the built-in font (DejaVu Sans) and its licence

A new window on the host is a new folder in host/ and a line about it in host/index.js, the only list of windows: the geometry of windows and the frame take the kinds of windows from there and keep no lists of their own. A neighbouring window is not edited for it (rule 2.10). A text one window says lies in its locales/; the common dictionary functions/ui/locales is for the shell, the common parts of the page and the function itself, and make ci checks that it holds no texts of one window. The body of a window is put together from host/frame.js, not drawn anew. A window takes its place in a bar by its description (bar, order), and the head of a bar is opened by the window that named it (heads); a new bar is an element in shell.js; a new button of a tab is an element of the list in the file of this window.

The mark for the shortcut is assets/ogas-mark.svg (used in ogas.desktop); in the window — window/ui/mark.svg, the icon of the program — window/icons/icon.ico.

A.5 A module — modules/<id>/

modules/<id>/
  manifest.json          the ports and parameters of the module
  main.py                the entry point: parsing a message and calling its task
  locales/{ru,en}.json   the name, description and hints of the module
  test_<id>.py           checks of the module without the platform, if there are any
sdk/                      OGAS SDK
  ogas-sdk               the author's command: new, check, try, pack, status, catalog, run
  python/                the SDK for Python; lies on the PYTHONPATH of a module
    ogas_runtime.py      a module in Python: the protocol, reading a step, the answer, a refusal, words, the memory of a node
    ogas_models.py       what modules with neural networks and pictures share
    ogas_assistant.py    what the networks of the assistant share
    ogas_check.py        checking a module without the platform: the contract by files and a conversation by the protocol
    ogas/                the package for programs outside: entering the platform, a program by script, the command ogas-sdk
  rust/                  the package ogas-module: the same for a module in Rust
  templates/             templates of modules
  networks/              the networks of the assistant — ready modules
  examples/              examples of modules and programs
  tests/                 checks of the SDK itself: a refusal, a failure in the work of a step, a crash, noise in stdout, cancelling
    doubles/<id>/        test modules: made like a module of the person, but not installed and not delivered
    live/<task>/         a trial on a live task: modules/<id>/ — its modules, process/ — processes, samples/ or make_reference.py — the source data;
                         not installed, not delivered, hold no model weights, make ci does not run them

A module does not link the code of a neighbouring module. What is common is only OGAS SDK (sdk/) and the exchange through stdin / stdout. What lies in the module folder — Modules, section 2.

A.6 Documents

The make-up of the documentation is the map of the documentation. The documentation is not part of the platform and not part of the delivery (Rules of development, 2.11).

The look of the workshop is tokens in lib/look.js and style.css inside functions/ui/window/ui/; the frame of a window is drawn by the frame (shell.js), a window on the host draws only its own content. The rule — The workshop, section 7, «One look of the shell».

A.7 Limits of the structure

• A new outside Rust library — only with a written reason (3.9).
• The set of technologies: JSON files, standard Rust threads, a module is an OS process, the window is a Windows program on Tauri 2 and WebView2, a page without a bundler and without a ready interface library.
• A document lies in the folder of its readers: docs/guide/, docs/reference/, docs/sdk/, docs/platform/, docs/contract/ (Rules of development, 5.1.3).
• Bars and the tabs of windows are drawn by the frame (shell.js, faces.js); a window on the host does not draw its capsule and does not set a colour as a number.
• A file is not split only because of the number of lines, in checks too.
• The main file does not do the work of a task: a task that has its own file is not written into main.rs.
• A default, a limit or a text for the person is not written in code: there is the schema file and the dictionaries of the part for them.

Appendix B (informative). Assumptions

• A module is trusted code and works with the rights of the user.
• The load is not set; large values are judged by measurements.
• There is no hard limit on the number of nodes and links: the limit is set by the resources of the machine.
• A JSON message up to 4 MiB is for service data; large data are passed as result files (artifacts), one up to 64 MiB by default.
• The required languages of the interface are Russian and English.
• Installing Python dependencies may need the network; installing without the network is not promised.