diff --git a/DEVELOPMENT_STATUS.md b/DEVELOPMENT_STATUS.md index eaac67b..29a345f 100644 --- a/DEVELOPMENT_STATUS.md +++ b/DEVELOPMENT_STATUS.md @@ -1,50 +1,95 @@ # Development Status -Last reviewed: 2026-05-11 +Last reviewed: 2026-05-27 ## What Currently Works -- Python development setup through `make setup`. -- Deterministic simulator scenarios through `make simulate`. -- JSONL ingestion, validation, and dead-letter handling through `make ingest`. -- Process Sentinel drift detection, evidence, and recommendation generation through `make sentinel-run`. -- FastAPI local API startup through `make api`, with auto-reload available through `make api-reload`. -- PostgreSQL Docker Compose configuration through `make dev-db`. -- Backend checks through `make lint`, `make typecheck`, and `make test`. +- Docker Compose starts the FIP `postgres`, `api`, `web`, + `connector-worker`, and `sentinel-worker` services. +- The Compose stack does not start an in-repo simulator container. + Demo-Factory runs separately as the local external protocol source fixture. +- The read-only connector worker loads Demo-Factory OPC-UA, MQTT, and BACnet + connection fixtures and normalizes source readings into FactoryEvents. +- Docker services use Postgres-backed runtime state by default through + `FACTORY_STORAGE_BACKEND=postgres`. +- The scheduled Process Sentinel worker reads stored FactoryEvents and writes + advisory detections, evidence, and recommendations. +- The FastAPI API exposes runtime health, connection profile diagnostics, + source inventory, detections, evidence, recommendations, and draft + investigation data. +- The Next.js Workbench renders the current operator console over API state. +- `make compose-smoke` validates API health, connector-ingested events, + readable Process Sentinel state, and Workbench rendering against the composed + runtime. +- Focused local checks are available through `make lint`, `make typecheck`, + `make test`, `make test-e2e`, and `cd apps/web && npm test`. ## What Is Incomplete -- `apps/web` is a placeholder; the Next.js workbench has not been implemented. -- `make test-e2e` is a documented placeholder until the web workbench exists. -- PostgreSQL is configured, but the default local MVP flow still uses JSONL storage. -- Real MQTT, OPC UA, MES, QMS, CMMS, and ERP connectors are out of scope for the current skeleton. -- Authentication, multi-tenant behavior, production deployment, and real industrial writeback are not implemented. +- Local Demo-Factory endpoints are development fixtures, not production + connectors or validation evidence. +- Authentication, multi-tenant behavior, production deployment, Kubernetes, + Helm, and high-availability operations are not implemented. +- Real industrial writeback, MQTT command publishing, BACnet writes, product + disposition, and QMS/MES writeback are intentionally out of scope. +- CI hardening for the full Docker Compose smoke path can still be improved + after the local runtime remains stable. -## How To Run The Current Skeleton +## How To Run The Current Runtime + +Start Demo-Factory separately from a sibling checkout: ```bash -make setup -make simulate SCENARIO=gradual_drift -make ingest INPUT=.local/events/gradual_drift.jsonl -make sentinel-run -make api +cd ../Demo-Factory +docker compose up -d --build +``` + +Start FIP from this repository: + +```bash +cd ../Factory-Intelligence-Platform +make compose-up +make compose-ps +make compose-logs ``` Then open: ```text http://127.0.0.1:8000/docs +http://127.0.0.1:3000 ``` -Optional local PostgreSQL: +Stop the FIP stack with: ```bash -make dev-db +make compose-down ``` +Use `docs/runtime/DOCKER_COMPOSE.md` for detailed startup, shutdown, rebuild, +logs, health, and smoke commands. Use `docs/runtime/TROUBLESHOOTING.md` when +Docker, Postgres, connector, API, or Workbench checks fail. + +## Focused Local Development + +For direct API or Workbench loops outside the full Compose stack: + +```bash +make setup +make api +cd apps/web +npm run dev +``` + +The repository still keeps JSONL-backed fixtures for fast unit and integration +tests. Use them only for focused regression work that intentionally does not +need Postgres or the full composed runtime. + ## Verified Commands ```bash +docker compose -f infra/docker/docker-compose.yml config +make compose-smoke make lint make typecheck make test @@ -52,17 +97,15 @@ make test-unit make test-integration make test-contract make test-e2e -make dev-db -docker compose -f infra/docker/docker-compose.yml config -docker compose -f infra/docker/docker-compose.yml ps +cd apps/web && npm test ``` -`make test-e2e` should print the placeholder message until the web workbench is implemented. -`make dev-db` should start a healthy PostgreSQL container on local port `5432`. - ## Recommended Next Steps -1. Harden shared event contracts with additional fixtures for recommendation, approval, and audit events. -2. Add the first minimal web workbench screen over the existing API state. -3. Replace the placeholder e2e command with a Playwright test once the workbench exists. -4. Decide when JSONL development storage should give way to the PostgreSQL-backed path for integration tests. +1. Keep Docker Compose runtime docs current as connector, API, and Workbench + behavior changes. +2. Harden CI around the Dockerized runtime when the local smoke path remains + stable enough for GitHub Actions. +3. Expand external-source coverage only through read-only connector boundaries. +4. Continue separating advisory recommendations from any future + human-approved action routing. diff --git a/README.md b/README.md index 3dbadf7..95149a6 100644 --- a/README.md +++ b/README.md @@ -94,8 +94,8 @@ See `docs/CONNECTOR_SAFETY_MODEL.md` for the current connector safety model. ## Local Runtime Commands -The Compose runtime is being introduced through epic #232. Start Demo-Factory -separately when validating external local protocol sources: +The Compose runtime from epic #232 is the current local integration path. Start +Demo-Factory separately when validating external local protocol sources: ```bash cd ../Demo-Factory diff --git a/apps/web/README.md b/apps/web/README.md index 29be1fe..199daea 100644 --- a/apps/web/README.md +++ b/apps/web/README.md @@ -2,10 +2,9 @@ Next.js operator-console shell for the Factory Intelligence Platform. -The Workbench is moving toward the Docker/Demo-Factory runtime direction: -external Demo-Factory protocol services feed FIP read-only connectors, which -normalize readings into FactoryEvents for Process Sentinel, the API, and the -Workbench. +The Workbench is part of the Docker/Demo-Factory runtime path: external +Demo-Factory protocol services feed FIP read-only connectors, which normalize +readings into FactoryEvents for Process Sentinel, the API, and the Workbench. ## Local Startup @@ -87,7 +86,7 @@ RCA/CAPA draft panels should be treated as missing runtime data until Demo-Factory, FIP Compose, connector ingestion, and Process Sentinel have all run. -For focused Workbench development before all Compose services land, run the API +For focused Workbench development outside the full Compose stack, run the API directly from the repository root: ```bash diff --git a/docs/DEMO_RUNBOOK.md b/docs/DEMO_RUNBOOK.md index db515d0..36b01a3 100644 --- a/docs/DEMO_RUNBOOK.md +++ b/docs/DEMO_RUNBOOK.md @@ -54,15 +54,15 @@ Use `docker compose down` for normal shutdown. Use `docker compose -f infra/docker/docker-compose.yml down -v` only when you intentionally want to delete FIP named volumes such as local Postgres data. -The Compose runtime is being built across the Dockerized runtime epic. Some -services may be placeholders until the child issues for API/web images, -connector worker, Postgres-backed runtime storage, Sentinel worker, and Compose -smoke tests land. +The Compose runtime is the current local integration path for FIP. It includes +the API, Workbench, Postgres, read-only connector worker, and Process Sentinel +worker. Use `make compose-smoke` with Demo-Factory already running separately +to verify API health, connector ingestion, Process Sentinel state, and +Workbench rendering. ## Focused Local Development -For focused API or Workbench development before the full Compose stack is -available: +For focused API or Workbench development outside the full Compose stack: ```bash make setup diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index a85adf6..9004173 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -84,9 +84,7 @@ Use `docker compose down` for normal shutdown. Use `docker compose -f infra/docker/docker-compose.yml down -v` only when you intentionally want to delete FIP named volumes such as local Postgres data. -Some Compose services are still landing through the Dockerized runtime epic. For -focused API or Workbench development before the full composed stack is -available, run: +For focused API or Workbench development outside the full composed stack, run: ```bash make setup @@ -121,10 +119,12 @@ Current skeleton components: - `packages/factory-events` — shared event contracts - `services/simulator` — legacy local fixture code, not the default runtime path -- `services/ingestion` — validation and dead-letter handling +- `services/ingestion` — read-only connector worker, validation, and + dead-letter handling - `services/process-sentinel` — drift rules, evidence, recommendations - `services/api` — FastAPI endpoints for the MVP state -- `infra/docker` — PostgreSQL compose config +- `infra/docker` — Docker Compose runtime for Postgres, API, Workbench, + connector worker, and Sentinel worker ## Connector Fixture Safety diff --git a/docs/LEARNING_LOG.md b/docs/LEARNING_LOG.md index c4f373e..bb30eb6 100644 --- a/docs/LEARNING_LOG.md +++ b/docs/LEARNING_LOG.md @@ -22,6 +22,68 @@ This file should be updated by Codex after each meaningful change. ### What to learn next ``` +## 2026-05-27 - Dockerized runtime epic status cleanup + +### What changed + +Updated current runtime status and runbook wording so the documentation treats +the Docker Compose path from epic #232 as the active local integration runtime, +not a future placeholder. Added regression coverage for stale wording that +would reintroduce the old placeholder or simulator-default framing. + +### Why it matters + +The child issues already supplied the composed API, Workbench, Postgres, +connector worker, Sentinel worker, external Demo-Factory source fixtures, and +Compose smoke path. Closing the epic safely requires the entry-point docs to +match that implemented behavior. + +### How it works + +The docs now describe Demo-Factory running separately, FIP Compose running the +platform services, connector ingestion normalizing source readings into +FactoryEvents, Postgres-backed runtime state in Docker, and Process Sentinel +reading that stored state. The doc regression test checks those claims and +blocks stale placeholder language from returning to current runtime docs. + +### How to run it + +```bash +cd ../Demo-Factory +docker compose up -d --build + +cd ../Factory-Intelligence-Platform +make compose-up +make compose-smoke +make compose-down +``` + +### How to test it + +```bash +.venv/bin/python -m pytest services/simulator/tests/test_runtime_docs_transition.py services/simulator/tests/test_docker_compose_runtime_docs.py +make lint +make typecheck +make test +cd apps/web && npm test +``` + +### Key files + +- `DEVELOPMENT_STATUS.md` +- `README.md` +- `docs/runtime/DOCKER_COMPOSE.md` +- `docs/DEMO_RUNBOOK.md` +- `docs/DEVELOPMENT.md` +- `apps/web/README.md` +- `services/ingestion/README.md` +- `services/simulator/tests/test_runtime_docs_transition.py` + +### What to learn next + +Keep the Docker Compose smoke path reliable enough to promote into CI without +turning local Demo-Factory fixtures into production-readiness evidence. + ## 2026-05-27 - Scheduled Process Sentinel worker ### What changed diff --git a/docs/demo/OPERATIONS_WORKBENCH_DEMO_RUNBOOK.md b/docs/demo/OPERATIONS_WORKBENCH_DEMO_RUNBOOK.md index 97ba104..61f77bf 100644 --- a/docs/demo/OPERATIONS_WORKBENCH_DEMO_RUNBOOK.md +++ b/docs/demo/OPERATIONS_WORKBENCH_DEMO_RUNBOOK.md @@ -3,7 +3,7 @@ ## Status This document replaces the old Workbench runbook for the in-repo generated-data -demo. The Workbench is moving toward the Dockerized FIP runtime where external +demo. The Workbench now aligns with the Dockerized FIP runtime where external Demo-Factory protocol services provide local source data. ## Current Direction @@ -31,7 +31,7 @@ cd ../Factory-Intelligence-Platform docker compose -f infra/docker/docker-compose.yml up --build ``` -For focused Workbench development before all Compose services land: +For focused Workbench development outside the full Compose stack: ```bash make api diff --git a/docs/runtime/DOCKER_COMPOSE.md b/docs/runtime/DOCKER_COMPOSE.md index e9501c8..313ff4d 100644 --- a/docs/runtime/DOCKER_COMPOSE.md +++ b/docs/runtime/DOCKER_COMPOSE.md @@ -16,10 +16,10 @@ Demo-Factory protocols -> Next.js Workbench ``` -The Dockerized runtime is being built across epic #232. The FIP Compose stack -now defines the API, Workbench, connector worker, Process Sentinel worker, and -Postgres service shape. `make compose-smoke` provides the current local -end-to-end smoke path for this composed runtime. +The Dockerized runtime from epic #232 is the current local integration path. +The FIP Compose stack defines the API, Workbench, connector worker, Process +Sentinel worker, and Postgres service shape. `make compose-smoke` provides the +local end-to-end smoke path for this composed runtime. ## Dependency Order diff --git a/services/ingestion/README.md b/services/ingestion/README.md index cf18610..fdfd081 100644 --- a/services/ingestion/README.md +++ b/services/ingestion/README.md @@ -5,7 +5,7 @@ FactoryEvent contracts and persists normalized events for downstream services. ## Current Runtime Direction -FIP is moving toward this Docker/Demo-Factory runtime path: +FIP uses this Docker/Demo-Factory runtime path for local integration: ```text Demo-Factory protocols @@ -69,9 +69,9 @@ dead-letter records with enough context for debugging. ## Focused Development -The repository still contains legacy local fixture commands and tests while the -Dockerized runtime is being completed. Use them only for focused regression -work on event validation and Process Sentinel behavior. +The repository still contains legacy local fixture commands and tests. Use them +only for focused regression work on event validation and Process Sentinel +behavior when Postgres and the full composed runtime are not needed. Run the focused ingestion tests from the repository root: diff --git a/services/simulator/tests/test_runtime_docs_transition.py b/services/simulator/tests/test_runtime_docs_transition.py index 4dbf5ba..7488d0a 100644 --- a/services/simulator/tests/test_runtime_docs_transition.py +++ b/services/simulator/tests/test_runtime_docs_transition.py @@ -5,6 +5,7 @@ REPO_ROOT = Path(__file__).resolve().parents[3] CURRENT_RUNTIME_DOCS = [ + REPO_ROOT / "DEVELOPMENT_STATUS.md", REPO_ROOT / "README.md", REPO_ROOT / "FILE_INDEX.md", REPO_ROOT / "apps" / "web" / "README.md", @@ -68,6 +69,16 @@ def test_current_docs_do_not_present_in_repo_generation_as_default_path() -> Non "make simulate SCENARIO=gradual_drift", "Synthetic Factory Simulator\n", "simulator-first", + "is being introduced through epic #232", + "is being built across epic #232", + "is being built across the Dockerized runtime epic", + "moving toward the Docker/Demo-Factory runtime direction", + "FIP is moving toward this Docker/Demo-Factory runtime path", + "Compose services are still landing", + "`apps/web` is a placeholder", + "the Next.js workbench has not been implemented", + "default local MVP flow still uses JSONL storage", + "make test-e2e` should print the placeholder message", ] for path in CURRENT_RUNTIME_DOCS: @@ -92,6 +103,26 @@ def test_runtime_docs_preserve_read_only_safety_boundary() -> None: assert term in content +def test_development_status_describes_completed_compose_runtime() -> None: + status = _read(REPO_ROOT / "DEVELOPMENT_STATUS.md") + + required_terms = [ + "Last reviewed: 2026-05-27", + "`postgres`, `api`, `web`", + "`connector-worker`", + "`sentinel-worker`", + "Demo-Factory runs separately", + "FACTORY_STORAGE_BACKEND=postgres", + "make compose-smoke", + "Next.js Workbench renders", + "docs/runtime/DOCKER_COMPOSE.md", + "docs/runtime/TROUBLESHOOTING.md", + ] + + for term in required_terms: + assert term in status + + def test_learning_log_documents_runtime_direction_without_rewriting_history() -> None: learning_log = _read(REPO_ROOT / "docs" / "LEARNING_LOG.md")