Correct the scratch-dir and embedded Tasks notes

hanzoai/sqlite 0.5.10 falls back to the OS temp dir, so the suite now
passes on macOS. The embedded Tasks socket also fails on a data dir's
first start, measured against the pushed binary.

Co-authored-by: Hanzo Dev <[email protected]>

CONTRIBUTING.md

@@ -21,10 +21,7 @@ GOWORK=off CGO_ENABLED=0 GOEXPERIMENT=jsonv2 go test -count=1 ./...
 golangci-lint run -c ./golangci.yml ./...
 ```
 
-On macOS two tests fail for want of RAM-backed storage: `TestTasksEmbed` in
-`core` and `TestOrgBaseIsEncryptedAtRest` in `plugins/org`. The encrypted SQLite
-codec will only decrypt into RAM, which is `/dev/shm` on Linux, or on macOS a
-`tmpfs` mount named by `HANZO_SQLITE_RAMFS_DIR`.
+The whole suite passes on macOS with those settings.
 
 ## Admin UI
 

LLM.md

@@ -54,13 +54,12 @@ CI (`hanzo.yml`) runs the Go gates with those three variables, runs
 `network/attack_vectors_test.go` apart from the passes. Do not use `make build`
 or `make ui`: they run pnpm in `ui/`, which does not exist.
 
-**Known failures on macOS.** With the test command above, 63 packages pass and
-two tests fail: `TestTasksEmbed` in `core` and `TestOrgBaseIsEncryptedAtRest` in
-`plugins/org`. Both open an encrypted SQLite file through the pure-Go codec,
-which decrypts only into RAM: `/dev/shm` on Linux, or a `tmpfs` named by
-`HANZO_SQLITE_RAMFS_DIR` (`sudo mount_tmpfs <dir>`). An `hdiutil` RAM disk does
-not count. `TestOAuth2ConfigValidate` and `TestOAuth2ProviderConfigValidate`
-pass.
+**macOS.** The whole suite passes with the test command above, including
+`TestTasksEmbed`, `TestOrgBaseIsEncryptedAtRest`, `TestOAuth2ConfigValidate` and
+`TestOAuth2ProviderConfigValidate`. The first two failed on a Mac before
+`hanzoai/sqlite` v0.5.10, whose pure-Go codec would decrypt only into RAM. It now
+prefers RAM (`HANZO_SQLITE_RAMFS_DIR` when it names a `tmpfs`, then `/dev/shm`)
+and falls back to the OS temp directory.
 
 ## What must stay true
 
@@ -148,7 +147,7 @@ is `BASE_FRAME_ANCESTORS` (default `'self'`). It signs in with IAM PKCE
 - `--publicDir` and `--indexFallback` do nothing: `apis.Serve` registers `GET /{path...}` before the binary's static route checks for one.
 - A fresh Base's `users.createRule` is `""`, so anonymous callers can create rows.
 - `examples/base` sets no `IAMOrg`, so `plugins/org` never reads the master key and org Bases open unencrypted.
-- With a relative data dir, `TASKS_EMBED` uses `base_/data/tasks.sock`, which `zap.Network` reads as a TCP address. The engine fails and `NewBaseApp` drops the error.
+- `TASKS_EMBED` fails and `NewBaseApp` drops the error when the default socket path is relative (`zap.Network` reads `base_/data/tasks.sock` as a TCP address) and on a data directory's first start (the engine binds before the directory exists).
 - The start banner prints `/v1/` and a Dashboard address whatever `BASE_API_PREFIX` and `BASE_ENABLE_ADMIN_UI` say.
 - No GitHub release after `v0.36.7-hanzo.1` carries binaries, so `base update` fails, and `ghcr.io/hanzoai/base` has no image for `v1.5.92` to `v1.5.96`.
 - `go install github.com/hanzoai/base/examples/base@<version>` fails on the `replace` in `go.mod`.

docs/config.md

@@ -183,7 +183,7 @@ variables.
 
 | Variable | Meaning |
 |---|---|
-| `HANZO_SQLITE_RAMFS_DIR` | Directory the pure-Go encrypted SQLite codec decrypts into. It must be RAM-backed: `/dev/shm` is used when this is unset, and on macOS only a `tmpfs` mount qualifies. With neither, an encrypted database does not open. |
+| `HANZO_SQLITE_RAMFS_DIR` | Where the pure-Go encrypted SQLite codec keeps its temporary plaintext copy, when this directory is RAM-backed (on macOS, a `tmpfs` mount). Otherwise the codec uses `/dev/shm`, and failing that the OS temp directory. The copy is deleted on close. |
 | `HOSTNAME` | Default replication node id. |
 
 ### The cli command

docs/listeners.md

@@ -87,16 +87,21 @@ With no peers it opens nothing.
 ## Embedded Tasks
 
 `TASKS_EMBED=true` runs the Tasks engine inside Base and listens for it at
-`TASKS_EMBED_ADDRESS`, by default `<data dir>/tasks.sock`. A path is a unix
-socket; anything else is `host:port`. When the engine fails to start, Base logs
-nothing and runs scheduled jobs on timers inside the process. Rule out these
-causes:
+`TASKS_EMBED_ADDRESS`, by default `<data dir>/tasks.sock`. An address that starts
+with `/`, `./`, `../` or `@` is a unix socket; anything else is `host:port`. When
+the engine cannot listen, Base logs nothing and runs scheduled jobs on timers
+inside the process. That happens when:
 
-- A relative data directory, such as the default `base_/data`. The socket path
-  then starts with neither `/` nor `./`, is read as a TCP address, and cannot
-  bind. Give an absolute `--dir` or `TASKS_EMBED_ADDRESS`.
-- No RAM-backed directory for the engine's encrypted store: `/dev/shm` on
-  Linux, or on macOS a `tmpfs` mount named by `HANZO_SQLITE_RAMFS_DIR`.
+- the address is a relative path without `./`. The default is one whenever the
+  data directory is relative, as the default `base_/data` is, and it is then
+  read as `host:port`;
+- the socket's directory does not exist yet. Base starts the engine before it
+  creates the data directory, so the default address fails on the first start
+  with a new data directory;
+- the path is too long for a unix socket. Keep it well under 100 bytes.
+
+A short absolute `TASKS_EMBED_ADDRESS` in a directory that already exists avoids
+each of these.
 
 ## KMS