Refreshed notes

notes/comm_arch.md

@@ -1,10 +1,15 @@
 # Communication Architecture
 
+The architecture of the communication layer between the interpreter and native extensions. Because this is an internal mechanism entirely, its _medium_ is the underlying communication channel
+
 - **Communication medium** 1-1 duplex ordered reliable and a request/reply notify protocol defined on top (`orchid-base` mostly)
 
 - **Protocol definition** plain objects that define nothing beside serialization/deserialization and English descriptions of invariants (`orchid-api`)
 
-- **Active objects** smart objects that represent resources and communicate commands and queries through the protocol, sorted into 3 categories for asymmetric communication: common/extension/host. Some ext/host logic is defined in `orchid-base` to ensure that other behaviour within it can rely on certain global functionality. ext/host also manage their respective connection state (`orchid-base`, `orchid-extension`, `orchid-host`)
+- **Active objects** most of the business logic, sorted into 3 categories for asymmetric communication: common/extension/host (`orchid-base`, `orchid-extension`, `orchid-host`). Smart objects that represent resources and communicate commands and queries through the protocol
 
-- **Application** (client, server) binaries that use active objects to implement actual application behaviour (`orcx`, `orchid-std`)
+  - **Service architecture** abstract interfaces and DI for broad capabilities like interning and scheduling (`orchid-base`), and their specific implementations in terms of local source of truth (`orchid-host`) and in terms of a global comms channel (`orchid-extension`)
+  
+  - **Connection terminals** terminals for establishing specific instances of the 1-1 ordered reliable channel that the comms protocol uses (`orchid-host`, `orchid-extensions`)
 
+- **Application** (client, server) binaries that use active objects to implement actual application behaviour (`orcx`, `orchid-std`)

notes/crates.md

@@ -18,12 +18,16 @@ Extension development toolkit. It routes the requests to handlers in a nice obje
 
 # orchid-base
 
-Common items used by both [`orchid-host`](#orchid-host) and [`orchid-extension`](#orchid-extension). Most notably, both sides of the string interner are defined here because it has to be callable from other items defined in this crate through the same set of global functions in both environments.
+Common items used by both [`orchid-host`](#orchid-host) and [`orchid-extension`](#orchid-extension). Most notably, the string interner's interface is defined here because it has to be callable from other items defined in this crate through the same set of global functions in both environments.
 
 # orchid-api
 
 Definition of the extension API. This crate should not contain any logic, it should hold only serializable message structs, and their relations should represent how they fit into the protocol.
 
+## orchid_api::binary
+
+ABI-stable structures to establish cooperative scheduling and serialized communication in a dynamically linked context. A lot of the structures here are direct equivalents of a Rust trait object with one obvious implementation, but conversion functions are in [`orchid-base`](#orchid-base) to keep this library as a contract.
+
 # orchid-api-derive
 
 Derive macros for the traits in [`orchid-api-traits`](#orchid-api-traits) to make the definitions in [`orchid-api`](#orchid-api) more concise.

notes/expr_refs.md

@@ -4,14 +4,13 @@ Reference loops are resource leaks. There are two primary ways to avoid referenc
 
 - Trees reference Constants
 - Constants reference their constituent Expressions
-- Expressions reference Atoms
-- During evaluation, Constants replace their unbound names with Constants
-	- There is a reference cycle here, but it always goes through a Constant.
-		> **todo** A potential fix may be to update all Constants to point to a dummy value before freeing Trees
+- Expressions reference Atoms that are not younger than them
+- Expressions reference Names
+  - During evaluation, Names are not replaced with the Constant they point to
 - Atoms reference the Systems that implement them
 - Atoms may reference Expressions that are not younger than them
 	- This link is managed by the System but tied to Atom and not System lifecycle
-	- Atoms can technically be applied to themselves, but it's a copying apply so it probably isn't a risk factor
+	- Atoms can technically be applied to themselves, but it's a copying apply which produces a new instance of the Atom
 - Systems reference the Extension that contains them
 - Extensions reference the Port that connects them
 	- The Extension signals the remote peer to disconnect on drop