docs: rename ProjectConfig to FoundryContext; describe extension mechanism

Author: olivermeyer

docs/decisions/0003-project-context-injection.md

@@ -62,106 +62,157 @@ foundry.configure(project_name="bridge", version=__version__, ...)
 locate_subclasses(BaseService)  # reads from global state
 
 def locate_subclasses(_class):
-    project_name = foundry.config.project_name
+    project_name = foundry.context.name
     ...
 ```
 
 * Pros: clean call sites; no threading of values
 * Cons: caller still computes the values (requirement #2 violated); global mutable state; harder to test
 
-**#4 `ProjectConfig` dataclass + `from_package()` classmethod**
+**#4 `FoundryContext` Pydantic model + `from_package()` classmethod**
 
-The library owns the derivation logic in `ProjectConfig.from_package(project_name)`, which reads from `importlib.metadata`, `sys.argv`, CI env vars, etc. Projects construct a config and pass it at call sites.
+The library owns the derivation logic in `FoundryContext.from_package(project_name)`, which reads from `importlib.metadata`, `sys.argv`, CI env vars, etc. Projects construct a context and pass it at call sites.
 
 ```python
-config = ProjectConfig.from_package("bridge")
-locate_subclasses(BaseService, config=config)
+ctx = FoundryContext.from_package("bridge")
+locate_subclasses(BaseService, context=ctx)
 ```
 
 * Pros: requirements #1 and #2 satisfied; typed; derivation logic lives once in the library
-* Cons: requirement #3 only partially satisfied — projects must hold and thread their own `config` reference to read derived values, which doesn't fully eliminate `_constants.py`
+* Cons: requirement #3 only partially satisfied — projects must hold and thread their own `context` reference to read derived values, which doesn't fully eliminate `_constants.py`
 
-**#5 `ProjectConfig.from_package()` + `configure()` + `foundry.config` accessor (combination of #3 and #4)**
+**#5 `FoundryContext.from_package()` + `configure()` + `foundry.context` accessor (combination of #3 and #4)**
 
-Extends #4 with a `configure()` call that stores the config as library-level state, exposed back to callers via `foundry.config`. Library functions fall back to the configured default but accept an explicit `config` override for testing.
+Extends #4 with a `configure()` call that stores the context as library-level state, exposed back to callers via `foundry.context`. Library functions fall back to the configured default but accept an explicit `context` override for testing.
 
 ```python
 # at startup — replaces _constants.py entirely
-foundry.configure(ProjectConfig.from_package("bridge"))
+foundry.configure(FoundryContext.from_package("bridge"))
 
 # library functions use the configured default
 locate_subclasses(BaseService)
 
-def locate_subclasses(_class: type, config: ProjectConfig | None = None) -> list:
-    config = config or foundry.config
+def locate_subclasses(_class: type, context: FoundryContext | None = None) -> list:
+    context = context or foundry.context
     ...
 
 # projects read derived values back from the library
-print(foundry.config.user_agent)
+print(foundry.context.version_full)
 
 # in tests — explicit override, no global state touched
-locate_subclasses(BaseService, config=ProjectConfig(name="test-project", ...))
+locate_subclasses(BaseService, context=FoundryContext(name="test-project", ...))
 ```
 
 * Pros: all four requirements satisfied; `_constants.py` can be deleted outright; ergonomic for production; testable without resetting global state
-* Cons: global mutable state, though contained — tests pass config explicitly and never need to reset it
+* Cons: global mutable state, though contained — tests pass context explicitly and never need to reset it
 
 ## Decision
 
-I suggest we use **#5**.
+We use **#5**.
 
-`ProjectConfig` holds project identity and build metadata. Runtime mode flags (`is_container`, `is_cli`, `is_test`, `is_library`) are only consumed by `sentry_initialize()`, so they live in a nested `SentryContext` rather than on `ProjectConfig` directly:
+### Naming
+
+The central type is named `FoundryContext` (not `ProjectConfig` or `ProjectContext`). Rationale:
+
+- "Config" was rejected because it implies values loaded from env vars or files; this object is derived at startup from `importlib.metadata`, `sys.argv`, and env vars — it is computed context, not configuration input. The existing `SentrySettings` type already uses the "settings/config" pattern for env-based values.
+- "Project" prefix was considered but doesn't communicate which library owns the type. Since `FoundryContext` is specifically the library's handle on a project, naming it after the library makes the dependency explicit and aids discoverability.
+- The name is consistent with `SentryContext` (also runtime-computed, also nested within the same design).
+
+### Structure
+
+`FoundryContext` is a frozen Pydantic model, making all instances immutable after construction. Runtime mode flags (`is_container`, `is_cli`, `is_test`, `is_library`) are only consumed by `sentry_initialize()`, so they live in a nested `SentryContext` rather than on `FoundryContext` directly:
 
 ```python
-@dataclass
-class SentryContext:
+class SentryContext(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
     is_container: bool
     is_cli: bool
     is_test: bool
     is_library: bool
 
 
-@dataclass
-class ProjectConfig:
+class FoundryContext(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
     name: str
     version: str
     version_full: str
     environment: str
     env_file: list[Path]
     repository_url: str = ""
     documentation_url: str = ""
-    sentry: SentryContext = field(default_factory=SentryContext)
+    sentry: SentryContext = Field(default_factory=SentryContext)
 ```
 
 Each project calls `configure()` once at startup. This single line replaces `_constants.py` entirely:
 
 ```python
-foundry.configure(ProjectConfig.from_package("bridge"))
+foundry.configure(FoundryContext.from_package("bridge"))
 ```
 
-The configured `ProjectConfig` is accessible anywhere via `foundry.config`:
+The configured `FoundryContext` is accessible anywhere via `foundry.context`:
 
 ```python
 # before: from bridge.utils._constants import __version_full__, __project_name__
 # after:
-foundry.config.version_full
-foundry.config.name
+foundry.context.version_full
+foundry.context.name
 ```
 
-All public library functions fall back to `foundry.config` but accept an explicit override:
+All public library functions fall back to `foundry.context` but accept an explicit override:
 
 ```python
-def locate_subclasses(_class: type, config: ProjectConfig | None = None) -> list:
-    config = config or foundry.config
+def locate_subclasses(_class: type, context: FoundryContext | None = None) -> list:
+    context = context or foundry.context
     ...
 ```
 
 `SentryContext` is kept separate from `SentrySettings` (which holds SDK configuration loaded from env vars). `SentryContext` is runtime-computed; `SentrySettings` is env-based.
 
+### Extending FoundryContext
+
+Projects that need additional context fields beyond the base set can subclass `FoundryContext`. The subclass overrides `from_package()` to compute its extra fields, using `model_dump()` to forward all base fields:
+
+```python
+class BridgeContext(FoundryContext):
+    tenant_id: str = ""
+    deployment_region: str = "eu-west-1"
+
+    @classmethod
+    def from_package(cls, package_name: str) -> "BridgeContext":
+        base = super().from_package(package_name)
+        return cls(
+            **base.model_dump(),
+            tenant_id=os.getenv("TENANT_ID", ""),
+            deployment_region=os.getenv("REGION", "eu-west-1"),
+        )
+```
+
+At startup the subclass instance is passed to `configure()` as usual:
+
+```python
+foundry.configure(BridgeContext.from_package("bridge"))
+```
+
+`foundry.context` is typed as `FoundryContext` — sufficient for all library functions. Project code that needs access to the extended fields keeps its own reference to the concrete instance:
+
+```python
+bridge_context = BridgeContext.from_package("bridge")
+foundry.configure(bridge_context)
+
+# library uses foundry.context (FoundryContext) — no project-specific fields needed
+# project code uses bridge_context directly for its own extended fields
+bridge_context.tenant_id
+```
+
+This avoids module-level generics (which are awkward in Python) while keeping both the library and project code fully typed without casts.
+
 ## Consequences
 
-- `_constants.py` is eliminated entirely across all projects; derivation logic lives once in the library and derived values are read back via `foundry.config`.
+- `_constants.py` is eliminated entirely across all projects; derivation logic lives once in the library and derived values are read back via `foundry.context`.
 - New projects (API servers and CLI tools alike) require a single `configure()` call and no boilerplate.
-- Production call sites are clean — no config threading.
-- Tests can pass a `ProjectConfig` directly without touching or resetting global state.
+- Production call sites are clean — no context threading.
+- Tests can pass a `FoundryContext` directly without touching or resetting global state.
 - `SentryContext` nesting makes it clear that the mode flags are Sentry-specific and not general-purpose project metadata.
+- Projects that need additional fields subclass `FoundryContext` and pass their subclass to `configure()`; they hold their own typed reference for project-specific access.