docs/02 notes/falinks public surfaces.md

@@ -4,7 +4,7 @@ date-created: 2026-08-31 21:32
 
 # Falinks Public Surfaces
 
-The project has three components:
+The project has two components:
 - `Falinks`: the library to resolve short links to fully qualified domain names.
 - `falinks` cli:
     - Non-interactive (use for one off requests or by agents)

docs/02 notes/machoke public surface.md

@@ -0,0 +1,46 @@
+---
+date-created: 2026-09-01 20:17
+---
+
+# Machoke Public Surface
+
+Machoke's primary goal is to be a common storage interface for different types of storage backends.
+
+The first Machoke user is [[falinks|Falinks]]. Its storage needs are simple.
+It just manages a flat list of keyed entries.
+
+The first backend for Machoke is just going to be a simple in-memory map that gets serialized on shutdown and loaded on startup.
+
+## Design
+
+### `Machoke` public interface
+
+| Method          | Parameters              | Returns          | Description                                          |
+| --------------- | ----------------------- | ---------------- | ---------------------------------------------------- |
+| `<constructor>` | `machoke::Options`      | `Result<Machoke<T>>`        | Creates the `Machoke` object.                        |
+| `get`           | `key: String`           | `Result<T>`      | Returns the stored value for the `key` if it exists. |
+| `set`           | `key: String, value: T` | `Result<()>`     | Stores the value using `key`.                        |
+| `delete`        | `key: String`           | `Result<bool>`   | Deletes the value if it exists for `key`.            |
+| `list`          |                         | `Result<Vec<machoke::Entry<T>>>` | Retrieves all stored, raw values.                    |
+
+
+#### machoke::Options
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `backend` | `Backend` | `Backend::Simple` | The storage backend to use. |
+| `path` | `std::path::PathBuf` | tbd | The path to the file/directory for the backend to use. |
+
+
+#### machoke::Entry
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `key` | `String` | The entry key. |
+| `value` | `T` | The stored value. |
+
+#### machoke::Error
+
+- `NotFound`: no value exists for the provided key.
+- `InvalidKey`: the provided key cannot be used.
+- `Backend`: the storage backend failed.

docs/03 wrk/machoke.md

@@ -0,0 +1,14 @@
+---
+date-created: 2026-09-01 20:17
+---
+
+# Machoke
+
+## Current focus
+
+Implement the simple backend.
+
+## References
+
+- [[machoke public surface]]
+- [[falinks public surfaces]]