shop audit

docs/shop.md

@@ -62,13 +62,16 @@ Every module goes through a content-addressed caching pipeline. The cache key is
 When loading a module, the shop checks (in order):
 
 1. **In-memory cache** — `use_cache[key]`, checked first on every `use()` call
-2. **Native dylib** — pre-compiled platform-specific `.dylib` in the content-addressed store
-3. **Cached .mach blob** — binary bytecode in `~/.pit/build/<hash>.mach`
-4. **Cached .mcode IR** — JSON IR in `~/.pit/build/<hash>.mcode`
-5. **Adjacent .mach/.mcode** — files alongside the source (e.g., `sprite.mach`)
-6. **Source compilation** — full pipeline: analyze, mcode, streamline, serialize
+2. **Installed dylib** — per-file `.dylib` in `~/.pit/lib/<pkg>/<stem>.dylib`
+3. **Internal symbols** — statically linked into the `pit` binary (fat builds)
+4. **Cached .mach blob** — binary bytecode in `~/.pit/build/<hash>`
+5. **Cached .mcode IR** — JSON IR in `~/.pit/build/<hash>.mcode`
+6. **Adjacent .mach/.mcode** — files alongside the source (e.g., `sprite.mach`)
+7. **Source compilation** — full pipeline: analyze, mcode, streamline, serialize
 
-Results from steps 4-6 are cached back to the content-addressed store for future loads.
+Dylib resolution wins over internal symbols, so a dylib in `lib/` can hot-patch a fat binary. Delete the dylib to fall back to the static version.
+
+Results from steps 5-7 are cached back to the content-addressed store for future loads.
 
 ### Content-Addressed Store
 
@@ -102,21 +105,10 @@ symbol:  js_gitea_pockle_world_john_prosperon_sprite_use
 
 ### C Resolution Sources
 
-1. **Internal symbols** — statically linked into the `pit` binary (core modules)
-2. **Per-module dylibs** — loaded from `~/.pit/lib/` via a manifest file
+1. **Installed dylibs** — per-file dylibs in `~/.pit/lib/<pkg>/<stem>.dylib` (deterministic paths, no manifests)
+2. **Internal symbols** — statically linked into the `pit` binary (fat builds)
 
-### Manifest Files
-
-Each package with C extensions has a manifest at `~/.pit/lib/<package>.manifest.json` mapping symbol names to dylib paths:
-
-```json
-{
-  "js_mypackage_render_use": "/Users/john/.pit/lib/mypackage_render.dylib",
-  "js_mypackage_audio_use": "/Users/john/.pit/lib/mypackage_audio.dylib"
-}
-```
-
-The shop loads manifests lazily on first access and caches them.
+Dylibs are checked first at each resolution scope, so an installed dylib always wins over a statically linked symbol. This enables hot-patching fat binaries by placing a dylib in `lib/`.
 
 ### Combined Resolution
 
@@ -147,11 +139,19 @@ The set of injected capabilities is controlled by `script_inject_for()`, which c
 ~/.pit/
 ├── packages/         # installed packages (directories and symlinks)
 │   └── core -> ...   # symlink to the ƿit core
-├── lib/              # compiled C extension dylibs + manifests
-├── build/            # content-addressed compilation cache
-│   ├── <hash>.mach   # cached bytecode blobs
+├── lib/              # INSTALLED per-file dylibs (persistent, human-readable)
+│   ├── core/
+│   │   ├── fd.dylib
+│   │   ├── time.dylib
+│   │   └── internal/
+│   │       └── os.dylib
+│   └── gitea_pockle_world_john_prosperon/
+│       ├── sprite.dylib
+│       └── render.dylib
+├── build/            # EPHEMERAL cache (safe to delete anytime)
+│   ├── <hash>        # cached bytecode blobs
 │   ├── <hash>.mcode  # cached JSON IR
-│   └── <hash>.<target>.dylib  # native compiled modules
+│   └── <hash>.o      # compiled object files
 ├── cache/            # downloaded package zip archives
 ├── lock.toml         # installed package versions and commit hashes
 └── link.toml         # local development link overrides