Pod Ecosystem — grove as catalog, pod as distribution unit

Status: implementation draft — seed 0.9.0, ridge 0.2.0, grove ~30 libs Goal: grove as a curated catalog of pods (lib/app/tool/game), pod as the Rust crate equivalent — src or bin per target/profile; seed resolves first in the central cache ~/.seed//usr/local/seed and only then on the site.

1. Concepts

• Grove: an index (seed/docs/book/libs-reference.md:42) of pods with name@x.y.z, kind (lib app tool), capabilities, platforms, interface_hash. It does not compile; it only lists.
• Pod: name@ver + kind + emit (src lib bin) + target (linux-x86_64 macos-aarch64 * generic) + profile (debug release). src = seed.toml + src/lib.sd + sdi; bin = libPOD.so/a + POD.sdi + build.json.
• Resolution: use "pod" → seed.lock (pod@ver sha256 emit) → central cache ~/.seed//usr/local/seed → GET /archive/ab/cd/sha256 (seed-site/src/registry.sd:504).

2. Central layout ~/.seed (user) and /usr/local/seed (system, sudo)

• ~/.seed/src/<pod>/<ver>/<sha256>/ — immutable src (seed.toml + src/ + sdi + interface_hash from seed/compiler/llvm/src/driver/library_store.c).
• ~/.seed/bin/<pod>/<ver>/<sha256>/<target>/<profile>/ — libPOD.so/a + POD.sdi + build.json (target + profile + interface_hash + SEED_CODE_SPLIT in the digest, as in seed/seed:25).
• ~/.seed/manifest.json + per-project seed.lock (pod = "ridge" version = "^0.2" sha256 = "ab12...").
• ~/.seed 700, /usr/local/seed 755 root:staff (install_layout in seed/tools/seed_tooling.py:2333 already does system → /usr/local/bin etc.; extend to src/bin).

seed install user vs system

• seed install pod@^0.2[:target] → ~/.seed/src miss → GET /archive/... → compiles into ~/.seed/bin/... (central, not ./target).
• sudo seed install pod@^0.2 (EUID==0) → /usr/local/seed/src|bin (install -o root:staff), SUDO_USER preserved for ~/.seed/credentials.toml (seed/compiler/llvm/src/driver/toolchain.c:1681).

3. Cache versioning (conflict-free)

• ~/.seed/bin/ridge/0.2.1/ab12/linux-x86_64/debug/ and .../0.3.0/cd34/... coexist; seed.lock pins ver+sha256, LD_LIBRARY_PATH/rpath points to the exact ver. soname libridge.so.0.2/0.3 avoids DT_NEEDED collisions.
• interface_hash changes (rowcodec V3 0b114783) → new sha256 → miss and recompile of only the affected pod.

4. Toolchain and library_store

• seed build does not write ./target; library_store records into ~/.seed/bin/... keyed by pod@ver+target+profile+interface_hash+SEED_CODE_SPLIT.
• debug vs release share src but keep separate bin per profile.

5. Registry seed-site

• archive/ab/cd/<sha256> is already content-addressed (seed-site/src/registry.sd:504), index/<name>.json + catalog.json with interface_hash and yank/deprecated.
• GET /api/toolchain/latest (seed-site/src/main.sd:50) with {"schema":1,"version":"0.9.0","files":{"linux-x86-64":{...}}} + interface_hash.

6. Next steps (2 weeks)

1. deterministic seed.lock + seed update
2. final site_db pg (ridge_open → pg_site_db when SEED_SITE_USE_PG=1)
3. promote_prod.sh with automatic human-reviewed after translate_i18n.py