Initial commit of manual

.gitignore

@@ -0,0 +1 @@
+book/

book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["Tony Garnock-Jones"]
+language = "en"
+multilingual = false
+src = "src"
+title = "The Synit Manual"

src/SUMMARY.md

@@ -0,0 +1,11 @@
+# Summary
+
+[Overview](./introduction.md)
+
+- [Architecture](./architecture.md)
+- [Installation](./install.md)
+- [Preserves](./preserves.md)
+- [Protocol](./protocol.md)
+
+[Glossary](./glossary.md)
+

src/architecture.md

@@ -0,0 +1,62 @@
+# Architecture
+
+> What is an architecture? It's the rules of the platform which are
+> true on any embodiment of it, not just the one you work on today.
+> These rules are aimed at programs (what are valid programs) and the
+> design (its invariants) both. — [Olivier
+> Giroux](https://twitter.com/__simt__/status/1489790925266059264),
+> Feb. 2022
+
+The **[Syndicated Actor Model
+(SAM)](./glossary.md#syndicated-actor-model)** is the core
+architecture of Synit. The SAM builds upon [E-style
+actors](./glossary.md#e), replacing message-exchange with
+eventually-consistent *state replication* as the fundamental building
+block for interaction. Both E and the SAM are instances of the [Object
+Capability (ocap) model](./glossary.md#object-capability-model), a
+[compositional](./glossary.md#compositional) approach to system
+security.
+
+The "feel" of the system is somewhere between Smalltalk-style
+object-orientation, publish-subscribe programming, E- or Erlang-style
+actor interaction, Prolog-style logic programming, and Esterel-style
+reactive dataflow.
+
+ 1. **Programs are Actors.** Synit *programs*
+    ("[actors](./glossary.md#actor)" in the SAM) interoperate by
+    *[dataspace](./glossary.md#dataspace)*-mediated exchange of
+    *[messages](./glossary.md#message)* and replication of
+    *[conversational state](./glossary.md#conversational-state)*
+    expressed as *[assertions](./glossary.md#assertion)*.
+
+ 2. **Ocaps for security and privacy.** The ocap model provides the
+    fundamental building blocks for secure composition of programs in
+    the system. Synit extends the core ocap model with
+    [Macaroon](./glossary.md#macaroon)-inspired *attenuation* of
+    capabilities, for both limiting visibility of state and
+    constraining access to behaviour.
+
+ 3. **Reactivity and homeostasis.** Programs publish relevant aspects
+    of their internal state to peers (usually by placing
+    [assertions](./glossary.md#assertion) in a dataspace). Peers
+    subscribe to those assertions, reacting to changes in state to
+    preserve overall system equilibrium.
+
+ 3. **Layered architecture.** Programs may or may not be structured
+    internally using SAM principles: the system as a whole is where
+    the architectural principles are applied. However, it often makes
+    good sense to use SAM principles *within* a given Synit program as
+    well as *between* programs.
+
+ 4. **Language-neutral.** Where possible, programs interoperate via a
+    simple [protocol](./protocol.md) across transports like TCP/IP,
+    WebSockets, and Unix sockets and pipes. Otherwise, they
+    interoperate using traditional Unix techniques. The concrete
+    syntax for the messages and assertions exchanged among programs is
+    the [Preserves](./preserves.md) data language.
+
+ 5. **Strongly typed.** Preserves [Schemas](./preserves.md#schemas)
+    describe the data exchanged among programs. Schemas compile to
+    type definitions in various programming languages, helping give an
+    ergonomic development experience as well as ensuring safety at
+    runtime.

src/glossary.md

@@ -0,0 +1,21 @@
+# Glossary
+
+## Syndicated Actor Model
+
+Often abbreviated **SAM**.
+
+## Object Capability Model
+
+## Facet
+## Assertion
+## Dataspace
+## System Layer
+## Actor
+## Message
+## Conversational State
+## Capability
+## Preserves
+## E
+## Compositional
+## Schema
+## Macaroon

src/install.md

@@ -0,0 +1 @@
+# Installation

src/introduction.md

@@ -0,0 +1,39 @@
+# The Synit Manual
+
+## Welcome!
+
+Synit is an experiment in applying the [Syndicated Actor
+Model](./glossary.md#syndicated-actor-model) to the [System
+Layer](./glossary.md#system-layer) of an operating system for personal
+computers, including laptops, desktops, and mobile phones.
+
+Synit builds upon the Linux kernel, but replaces many pieces of
+familiar Linux software, including `systemd`, `NetworkManager`,
+`D-Bus`, and so on. It makes use of many concepts that will be
+familiar to Linux users, but also incorporates many ideas drawn from
+programming languages and operating systems not closely connected with
+Linux's Unix heritage.
+
+It is currently **experimental** software.
+
+ - Project homepage: <https://synit.org/>
+ - Source code: <https://git.syndicate-lang.org/>
+
+## Quickstart
+
+If you have a mobile phone or computer capable of running
+[PostmarketOS](https://postmarketos.org/), then you can
+[install](./install.md) the software to try it out. You can also run
+Synit inside a virtual machine.
+
+See the [installation instructions](./install.md) for a list of
+supported devices.
+
+## Acknowledgements
+
+Much initial work on Synit was made possible by a generous grant from
+the [NLnet Foundation](https://nlnet.nl/) as part of the [NGI
+Zero](https://nlnet.nl/NGI0/) [PET](https://nlnet.nl/PET/) programme.
+Please see "[Structuring the System Layer with Dataspaces
+(2021)](https://syndicate-lang.org/projects/2021/system-layer/)" for
+details of the funded project.

src/preserves.md

@@ -0,0 +1,9 @@
+# Preserves
+
+an S-expression-like language that is a syntactic superset of
+JSON. Like JSON, Preserves is not specifically tied to any
+particular programming language. Unlike JSON, Preserves has a
+robust semantics, designed specifically to be a solid foundation
+for networked communication.
+
+## Schemas

src/protocol.md

@@ -0,0 +1 @@
+# Protocol