CLAUDE.md@crates/orbit-common git:20261018.ce4a673A

Immutable. This exact content never changes and is served at /api/v1/blob/ea68b73c787c627a.

# orbit-common

Mechanisms every layer needs: `OrbitError` plus responsibility-named modules (`error`, `fs`, `governance`, `migration`, `model`, `observability`, `process`, `protocol`, `security`, `storage`). No feature, runtime, or storage backend. `orbit-types` says what a thing is; this crate says how to do something with it.

- Never add a module named after a caller or a vertical feature. If code fits no existing responsibility, it belongs in the crate that needs it. `mod.rs` = declarations + `#[cfg(test)] mod tests;` only.
- Single-owner invariants — never reimplement at a call site:
  - `security::child_env` — the only agent-subprocess env builder; allowlist over a cleared environment.
  - `security::release` — the release keys and manifest verification for the workspace crates. The desktop app, a separate workspace, keeps a copy in `desktop/src/update/trust.rs`; `scripts/check-installer-pubkey.sh` guards drift between them and the shell/npm installers.
  - `security::redaction` — the only redaction implementation (guardrail script forbids surface-local `fn redact_*`).
  - `fs::selector` — owns `SelectorParseError` and its `OrbitError` translator; no caller crate may translate it.
  - `error` — owns the `impl From<orbit_types::…Error> for OrbitError` translators, since `orbit-types` cannot name `OrbitError`; each is listed in `from_registry` in `scripts/check-error-translation.sh`.
  - `migration` — forward-only, read-time YAML migration; no rollback, no write-back. One-shot importers belong in `orbit-store::workflow`.
- `governance::operation` is the operations-as-data kernel; specs live here, handlers live in `orbit-core` joined by the verb enum. Keep it transport/runtime-agnostic: no clap, axum, or `OrbitRuntime` types. Every registry string is shipped contract.
- Features: `sqlite` gates `storage::sqlite`. Test helpers are always compiled so build and test dependency graphs stay identical. Gate optional production code behind the flag, don't `#[allow]` it.