fix: code improvements and documentation fixes

- Add date range filter to SalesDaily cleanup in ingest tests
- Enforce artifact_hash presence before verification in registry routes
- Compute SHA256 from saved file instead of source in storage
- Fix override_get_db to mirror production transaction semantics
- Filter DeploymentAlias cleanup to only test runs
- Update database port to 5433 in config and .env.example
- Add language identifiers to fenced code blocks (MD040)
- Fix table formatting for markdownlint MD060
- Update PR reference in PHASE/6-MODEL_REGISTRY.md
- Convert bare URLs to markdown links in INITIAL-7.md
- Wrap __init__.py in backticks in PRP-7

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: w7-learn

.env.example

@@ -2,7 +2,7 @@
 # Copy this file to .env and adjust values as needed
 
 # Database connection (PostgreSQL + pgvector via Docker Compose)
-DATABASE_URL=postgresql+asyncpg://forecastlab:forecastlab@localhost:5432/forecastlab
+DATABASE_URL=postgresql+asyncpg://forecastlab:forecastlab@localhost:5433/forecastlab
 
 # Application settings
 APP_NAME=ForecastLabAI

INITIAL-7.md

@@ -32,8 +32,8 @@
 ## DOCUMENTATION:
 - Postgres JSONB patterns
 - Artifact integrity (hashing) best practices
-- https://scalegrid.io/blog/using-jsonb-in-postgresql-how-to-effectively-store-index-json-data-in-postgresql/
-- https://www.fortra.com/blog/supply-chain-vulnerability
+- [Using JSONB in PostgreSQL](https://scalegrid.io/blog/using-jsonb-in-postgresql-how-to-effectively-store-index-json-data-in-postgresql/)
+- [Supply Chain Vulnerability](https://www.fortra.com/blog/supply-chain-vulnerability)
 
 ## OTHER CONSIDERATIONS:
 - No hardcoded artifact paths: derived from `ARTIFACT_ROOT` + run_id.

PRPs/PRP-7-model-registry.md

@@ -1050,14 +1050,14 @@ IMPLEMENT:
   - compare_runs.py: Compare two runs, show config/metrics diff
 ```
 
-### Task 18: Update module __init__.py exports
+### Task 18: Update module `__init__.py` exports
 
 ```yaml
 FILE: app/features/registry/__init__.py
 ACTION: MODIFY
 IMPLEMENT:
   - Export all public classes
-  - __all__ list (sorted alphabetically)
+  - `__all__` list (sorted alphabetically)
 VALIDATION:
   - uv run python -c "from app.features.registry import *; print('OK')"
 ```

app/core/config.py

@@ -21,7 +21,7 @@ class Settings(BaseSettings):
     debug: bool = False
 
     # Database
-    database_url: str = "postgresql+asyncpg://forecastlab:forecastlab@localhost:5432/forecastlab"
+    database_url: str = "postgresql+asyncpg://forecastlab:forecastlab@localhost:5433/forecastlab"
 
     # Logging
     log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = "INFO"

app/features/ingest/tests/test_routes.py

@@ -46,7 +46,11 @@ async def db_session():
     async with async_session_maker() as cleanup_session:
         with suppress(Exception):
             # Clean up test data (delete in correct order due to FK constraints)
-            await cleanup_session.execute(delete(SalesDaily))
+            await cleanup_session.execute(
+                delete(SalesDaily).where(
+                    (SalesDaily.date >= date(2024, 1, 1)) & (SalesDaily.date <= date(2024, 12, 31))
+                )
+            )
             await cleanup_session.execute(delete(Product).where(Product.sku.like("SKU-%")))
             await cleanup_session.execute(delete(Store).where(Store.code.like("S00%")))
             await cleanup_session.execute(

app/features/registry/routes.py

@@ -349,6 +349,12 @@ async def verify_artifact(
             detail="Run has no associated artifact",
         )
 
+    if run.artifact_hash is None:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Run has no stored artifact hash",
+        )
+
     storage = LocalFSProvider()
 
     try:

app/features/registry/storage.py

@@ -182,13 +182,13 @@ def save(self, source_path: Path, artifact_uri: str) -> tuple[str, int]:
         dest_path = self._resolve_path(artifact_uri)
         dest_path.parent.mkdir(parents=True, exist_ok=True)
 
-        # Compute hash before copy
-        file_hash = self.compute_hash(source_path)
-        file_size = source_path.stat().st_size
-
-        # Copy file
+        # Copy file first
         shutil.copy2(source_path, dest_path)
 
+        # Compute hash and size from the saved file
+        file_hash = self.compute_hash(dest_path)
+        file_size = dest_path.stat().st_size
+
         logger.info(
             "registry.artifact_saved",
             artifact_uri=artifact_uri,

app/features/registry/tests/conftest.py

@@ -8,7 +8,7 @@
 
 import pytest
 from httpx import ASGITransport, AsyncClient
-from sqlalchemy import delete
+from sqlalchemy import delete, select
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
 
 from app.core.config import get_settings
@@ -45,7 +45,11 @@ async def db_session() -> AsyncGenerator[AsyncSession, None]:
             yield session
         finally:
             # Clean up test data (delete in correct order due to FK constraints)
-            await session.execute(delete(DeploymentAlias))
+            # Only delete aliases for test runs (those with model_type.like("test-%"))
+            test_run_ids = select(ModelRun.id).where(ModelRun.model_type.like("test-%"))
+            await session.execute(
+                delete(DeploymentAlias).where(DeploymentAlias.run_id.in_(test_run_ids))
+            )
             await session.execute(delete(ModelRun).where(ModelRun.model_type.like("test-%")))
             await session.commit()
 
@@ -57,7 +61,12 @@ async def client(db_session: AsyncSession) -> AsyncGenerator[AsyncClient, None]:
     """Create test client with database dependency override."""
 
     async def override_get_db() -> AsyncGenerator[AsyncSession, None]:
-        yield db_session
+        try:
+            yield db_session
+            await db_session.commit()
+        except Exception:
+            await db_session.rollback()
+            raise
 
     app.dependency_overrides[get_db] = override_get_db
 

docs/ARCHITECTURE.md

@@ -321,7 +321,7 @@ forecast_enable_lightgbm: bool = False
 - `DeploymentAlias` - Mutable pointers to successful runs for deployment
 
 **Run Lifecycle (State Machine):**
-```
+```text
 PENDING → RUNNING → SUCCESS/FAILED → ARCHIVED
 ```
 - Validated transitions prevent invalid state changes

docs/PHASE/4-FORECASTING.md

@@ -38,12 +38,12 @@ class BaseForecaster(ABC):
 
 **Model Types Implemented**:
 
-| Model | Class | Description | Key Parameter |
+|Model|Class|Description|Key Parameter|
 |-------|-------|-------------|---------------|
-| `naive` | `NaiveForecaster` | Predicts last observed value for all horizons | None |
-| `seasonal_naive` | `SeasonalNaiveForecaster` | Predicts value from same season in previous cycle | `season_length` (default: 7) |
-| `moving_average` | `MovingAverageForecaster` | Predicts mean of last N observations | `window_size` (default: 7) |
-| `lightgbm` | (Placeholder) | LightGBM regressor (feature-flagged) | `n_estimators`, `max_depth`, `learning_rate` |
+|`naive`|`NaiveForecaster`|Predicts last observed value for all horizons|None|
+|`seasonal_naive`|`SeasonalNaiveForecaster`|Predicts value from same season in previous cycle|`season_length` (default: 7)|
+|`moving_average`|`MovingAverageForecaster`|Predicts mean of last N observations|`window_size` (default: 7)|
+|`lightgbm`|(Placeholder)|LightGBM regressor (feature-flagged)|`n_estimators`, `max_depth`, `learning_rate`|
 
 **FitResult Dataclass**:
 ```python
@@ -62,18 +62,18 @@ class FitResult:
 
 Pydantic v2 schemas with frozen configs for reproducibility:
 
-| Schema | Purpose |
+|Schema|Purpose|
 |--------|---------|
-| `ModelConfigBase` | Base with `schema_version` and `config_hash()` |
-| `NaiveModelConfig` | Config for naive forecaster |
-| `SeasonalNaiveModelConfig` | Config with `season_length` (1-365) |
-| `MovingAverageModelConfig` | Config with `window_size` (1-90) |
-| `LightGBMModelConfig` | Config for LightGBM (n_estimators, max_depth, learning_rate) |
-| `TrainRequest` | API request with store_id, product_id, date range, config |
-| `TrainResponse` | Response with model_path, n_observations, duration_ms |
-| `PredictRequest` | Request with horizon (1-90), model_path |
-| `PredictResponse` | Response with forecast points |
-| `ForecastPoint` | Single forecast with date, value, optional bounds |
+|`ModelConfigBase`|Base with `schema_version` and `config_hash()`|
+|`NaiveModelConfig`|Config for naive forecaster|
+|`SeasonalNaiveModelConfig`|Config with `season_length` (1-365)|
+|`MovingAverageModelConfig`|Config with `window_size` (1-90)|
+|`LightGBMModelConfig`|Config for LightGBM (n_estimators, max_depth, learning_rate)|
+|`TrainRequest`|API request with store_id, product_id, date range, config|
+|`TrainResponse`|Response with model_path, n_observations, duration_ms|
+|`PredictRequest`|Request with horizon (1-90), model_path|
+|`PredictResponse`|Response with forecast points|
+|`ForecastPoint`|Single forecast with date, value, optional bounds|
 
 **Key Features**:
 - Frozen models (`frozen=True`) for immutability
@@ -150,10 +150,10 @@ class ForecastingService:
 
 **File**: `app/features/forecasting/routes.py`
 
-| Endpoint | Method | Description |
+|Endpoint|Method|Description|
 |----------|--------|-------------|
-| `/forecasting/train` | POST | Train a forecasting model |
-| `/forecasting/predict` | POST | Generate forecasts using trained model |
+|`/forecasting/train`|POST|Train a forecasting model|
+|`/forecasting/predict`|POST|Generate forecasts using trained model|
 
 **Train Request Example**:
 ```json
@@ -204,12 +204,12 @@ class ForecastingService:
 
 **Directory**: `app/features/forecasting/tests/`
 
-| File | Tests | Coverage |
+|File|Tests|Coverage|
 |------|-------|----------|
-| `test_schemas.py` | 20 | Schema validation, config hash, frozen models |
-| `test_models.py` | 24 | Model fit/predict, edge cases, params |
-| `test_persistence.py` | 15 | Save/load bundles, version compatibility |
-| `test_service.py` | 20 | Service integration, validation, logging |
+|`test_schemas.py`|20|Schema validation, config hash, frozen models|
+|`test_models.py`|24|Model fit/predict, edge cases, params|
+|`test_persistence.py`|15|Save/load bundles, version compatibility|
+|`test_service.py`|20|Service integration, validation, logging|
 
 **Total**: 79 tests
 
@@ -223,11 +223,11 @@ class ForecastingService:
 
 **Directory**: `examples/models/`
 
-| File | Description |
+|File|Description|
 |------|-------------|
-| `baseline_naive.py` | Naive forecaster demo |
-| `baseline_seasonal.py` | Seasonal naive with weekly seasonality |
-| `baseline_mavg.py` | Moving average with configurable window |
+|`baseline_naive.py`|Naive forecaster demo|
+|`baseline_seasonal.py`|Seasonal naive with weekly seasonality|
+|`baseline_mavg.py`|Moving average with configurable window|
 
 ---
 
@@ -246,19 +246,19 @@ forecast_model_artifacts_dir: str = "./artifacts/models"
 forecast_enable_lightgbm: bool = False
 ```
 
-| Setting | Default | Description |
+|Setting|Default|Description|
 |---------|---------|-------------|
-| `forecast_random_seed` | 42 | Random seed for reproducibility |
-| `forecast_default_horizon` | 14 | Default forecast horizon in days |
-| `forecast_max_horizon` | 90 | Maximum allowed horizon |
-| `forecast_model_artifacts_dir` | `./artifacts/models` | Directory for saved models |
-| `forecast_enable_lightgbm` | False | Feature flag for LightGBM models |
+|`forecast_random_seed`|42|Random seed for reproducibility|
+|`forecast_default_horizon`|14|Default forecast horizon in days|
+|`forecast_max_horizon`|90|Maximum allowed horizon|
+|`forecast_model_artifacts_dir`|`./artifacts/models`|Directory for saved models|
+|`forecast_enable_lightgbm`|False|Feature flag for LightGBM models|
 
 ---
 
 ## Directory Structure
 
-```
+```text
 app/features/forecasting/
 ├── __init__.py          # Module exports
 ├── models.py            # BaseForecaster + implementations
@@ -284,7 +284,7 @@ examples/models/
 
 ## Validation Results
 
-```
+```bash
 $ uv run ruff check app/features/forecasting/
 All checks passed!
 
@@ -302,16 +302,16 @@ $ uv run pytest app/features/forecasting/tests/ -v
 
 ## Logging Events
 
-| Event | Description |
+|Event|Description|
 |-------|-------------|
-| `forecasting.train_request_received` | Train request received |
-| `forecasting.train_request_completed` | Training completed successfully |
-| `forecasting.train_request_failed` | Training failed |
-| `forecasting.predict_request_received` | Prediction request received |
-| `forecasting.predict_request_completed` | Prediction completed |
-| `forecasting.predict_request_failed` | Prediction failed |
-| `forecasting.model_saved` | Model bundle saved to disk |
-| `forecasting.model_loaded` | Model bundle loaded from disk |
+|`forecasting.train_request_received`|Train request received|
+|`forecasting.train_request_completed`|Training completed successfully|
+|`forecasting.train_request_failed`|Training failed|
+|`forecasting.predict_request_received`|Prediction request received|
+|`forecasting.predict_request_completed`|Prediction completed|
+|`forecasting.predict_request_failed`|Prediction failed|
+|`forecasting.model_saved`|Model bundle saved to disk|
+|`forecasting.model_loaded`|Model bundle loaded from disk|
 
 ---