shop audit

docs/c-modules.md

@@ -52,6 +52,11 @@ Where:
 Examples:
 - `mypackage/math.c` -> `js_mypackage_math_use`
 - `gitea.pockle.world/john/lib/render.c` -> `js_gitea_pockle_world_john_lib_render_use`
+- `mypackage/game.ce` (AOT actor) -> `js_mypackage_game_program`
+
+Actor files (`.ce`) use the `_program` suffix instead of `_use`.
+
+**Note:** Having both a `.cm` and `.c` file with the same stem at the same scope is a build error.
 
 ## Required Headers
 

docs/cli.md

@@ -70,10 +70,11 @@ pit ls <package>    # list files in specified package
 
 ### pit build
 
-Build the current package.
+Build the current package. Compiles C files into per-file dynamic libraries and installs them to `~/.pit/lib/<pkg>/<stem>.dylib`.
 
 ```bash
-pit build
+pit build              # build current package
+pit build <package>    # build specific package
 ```
 
 ### pit test
@@ -159,9 +160,11 @@ pit install /Users/john/work/mylib
 
 ```
 ~/.pit/
-├── packages/       # installed packages
-├── lib/            # compiled dynamic libraries
-├── build/          # build cache
+├── packages/       # installed package sources
+├── lib/            # installed per-file dylibs (persistent)
+│   ├── core/       # core package dylibs
+│   └── <pkg>/      # per-package subdirectories
+├── build/          # ephemeral build cache (safe to delete)
 ├── cache/          # downloaded archives
 ├── lock.toml       # installed package versions
 └── link.toml       # local development links

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