diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 4ae1613..3068c29 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -41,26 +41,36 @@ These rules govern every task. Any deviation must be discussed and documented as ### Phase 1 โ€” Inbound telemetry (Codec 8, 8E, 16) -**Status:** โฌœ Not started +**Status:** ๐ŸŸจ In progress (core implementation done; observability + hardening + device authority paused for pilot test) **Outcome:** A production-ready Node.js TCP server ingesting Teltonika telemetry from any FMB/FMC/FMM/FMU device, publishing normalized `Position` records to Redis Streams, with full observability and CI/CD via Gitea. [**See `phase-1-telemetry/README.md`**](./phase-1-telemetry/README.md) -| # | Task | Status | -|---|------|--------| -| 1.1 | [Project scaffold](./phase-1-telemetry/01-project-scaffold.md) | โฌœ | -| 1.2 | [Core shell & framing types](./phase-1-telemetry/02-core-shell.md) | โฌœ | -| 1.3 | [Configuration & logging](./phase-1-telemetry/03-config-and-logging.md) | โฌœ | -| 1.4 | [Teltonika framing layer (envelope, CRC, handshake)](./phase-1-telemetry/04-teltonika-framing.md) | โฌœ | -| 1.5 | [Codec 8 parser](./phase-1-telemetry/05-codec-8.md) | โฌœ | -| 1.6 | [Codec 8 Extended parser (incl. NX)](./phase-1-telemetry/06-codec-8-extended.md) | โฌœ | -| 1.7 | [Codec 16 parser (incl. Generation Type)](./phase-1-telemetry/07-codec-16.md) | โฌœ | -| 1.8 | [Redis Streams publisher & main wiring](./phase-1-telemetry/08-redis-publisher.md) | โฌœ | -| 1.9 | [Fixture suite & testing strategy](./phase-1-telemetry/09-fixture-suite.md) | โฌœ | -| 1.10 | [Observability (Prometheus metrics)](./phase-1-telemetry/10-observability.md) | โฌœ | -| 1.11 | [Dockerfile & Gitea workflow](./phase-1-telemetry/11-dockerfile-and-ci.md) | โฌœ | -| 1.12 | [Production hardening](./phase-1-telemetry/12-production-hardening.md) | โฌœ | -| 1.13 | [Device authority (Redis allow-list refresher)](./phase-1-telemetry/13-device-authority.md) | โฌœ | +| # | Task | Status | Landed in | +|---|------|--------|-----------| +| 1.1 | [Project scaffold](./phase-1-telemetry/01-project-scaffold.md) | ๐ŸŸฉ | `1e9219d` | +| 1.2 | [Core shell & framing types](./phase-1-telemetry/02-core-shell.md) | ๐ŸŸฉ | `1e9219d` | +| 1.3 | [Configuration & logging](./phase-1-telemetry/03-config-and-logging.md) | ๐ŸŸฉ | `1e9219d` | +| 1.4 | [Teltonika framing layer (envelope, CRC, handshake)](./phase-1-telemetry/04-teltonika-framing.md) | ๐ŸŸฉ | `1e9219d` | +| 1.5 | [Codec 8 parser](./phase-1-telemetry/05-codec-8.md) | ๐ŸŸฉ | `381287b` | +| 1.6 | [Codec 8 Extended parser (incl. NX)](./phase-1-telemetry/06-codec-8-extended.md) | ๐ŸŸฉ | `381287b` | +| 1.7 | [Codec 16 parser (incl. Generation Type)](./phase-1-telemetry/07-codec-16.md) | ๐ŸŸฉ | `381287b` | +| 1.8 | [Redis Streams publisher & main wiring](./phase-1-telemetry/08-redis-publisher.md) | ๐ŸŸฉ | `af06973` | +| 1.9 | [Fixture suite & testing strategy](./phase-1-telemetry/09-fixture-suite.md) | ๐ŸŸฉ | `381287b` | +| 1.10 | [Observability (Prometheus metrics)](./phase-1-telemetry/10-observability.md) | โธ | *deferred โ€” see below* | +| 1.11 | [Dockerfile & Gitea workflow](./phase-1-telemetry/11-dockerfile-and-ci.md) | โฌœ | *next, in slim form for the pilot* | +| 1.12 | [Production hardening](./phase-1-telemetry/12-production-hardening.md) | โธ | *deferred โ€” see below* | +| 1.13 | [Device authority (Redis allow-list refresher)](./phase-1-telemetry/13-device-authority.md) | โธ | *deferred โ€” see below* | + +#### Deferred (resume after the real-device pilot test) + +These three tasks are paused so we can get the service onto real hardware as fast as possible. They are paused, not cancelled โ€” each must be completed before the service is considered production-ready. + +- **1.10 Observability (Prometheus metrics).** Tracking via the placeholder `Metrics` interface for now. **Resume trigger:** as soon as the pilot is generating real traffic and we want to measure it, *or* before any second instance is deployed (without metrics, "consumer lag" and "unknown codec" alerts cannot fire). +- **1.12 Production hardening.** Graceful shutdown is a stub today; uncaught-exception handlers are minimal. **Resume trigger:** before the pilot graduates to "always-on" or before any deployment that does rolling restarts. Acceptable for a manual pilot where we can stop/start the process by hand. +- **1.13 Device authority (Redis allow-list refresher).** Default `AllowAllAuthority` accepts every IMEI; observability of `known | unknown` is moot until 1.10 lands. **Resume trigger:** when Directus has a `devices` collection publishing the allow-list to Redis, or when the operational picture demands rejecting unknown IMEIs (`STRICT_DEVICE_AUTH=true`). + +When resuming any of these, change the status from โธ back to โฌœ or ๐ŸŸจ here and in the task file's status badge, and clear the deferral note in the task file. ### Phase 2 โ€” Outbound commands (Codec 12, 14) diff --git a/.planning/phase-1-telemetry/01-project-scaffold.md b/.planning/phase-1-telemetry/01-project-scaffold.md index fa1f299..7308f4e 100644 --- a/.planning/phase-1-telemetry/01-project-scaffold.md +++ b/.planning/phase-1-telemetry/01-project-scaffold.md @@ -1,7 +1,7 @@ # Task 1.1 โ€” Project scaffold **Phase:** 1 โ€” Inbound telemetry -**Status:** โฌœ Not started +**Status:** ๐ŸŸฉ Done โ€” landed in commit `1e9219d` **Depends on:** None **Wiki refs:** `docs/wiki/sources/teltonika-ingestion-architecture.md` ยง Project location and layout diff --git a/.planning/phase-1-telemetry/02-core-shell.md b/.planning/phase-1-telemetry/02-core-shell.md index 929a382..f6696c5 100644 --- a/.planning/phase-1-telemetry/02-core-shell.md +++ b/.planning/phase-1-telemetry/02-core-shell.md @@ -1,7 +1,7 @@ # Task 1.2 โ€” Core shell & framing types **Phase:** 1 โ€” Inbound telemetry -**Status:** โฌœ Not started +**Status:** ๐ŸŸฉ Done โ€” landed in commit `1e9219d` **Depends on:** 1.1 **Wiki refs:** `docs/wiki/concepts/protocol-adapter.md`, `docs/wiki/concepts/codec-dispatch.md`, `docs/wiki/concepts/position-record.md` diff --git a/.planning/phase-1-telemetry/03-config-and-logging.md b/.planning/phase-1-telemetry/03-config-and-logging.md index ece8173..ff0c4ad 100644 --- a/.planning/phase-1-telemetry/03-config-and-logging.md +++ b/.planning/phase-1-telemetry/03-config-and-logging.md @@ -1,7 +1,7 @@ # Task 1.3 โ€” Configuration & logging **Phase:** 1 โ€” Inbound telemetry -**Status:** โฌœ Not started +**Status:** ๐ŸŸฉ Done โ€” landed in commit `1e9219d` **Depends on:** 1.1 **Wiki refs:** `docs/wiki/sources/gps-tracking-architecture.md` ยง Deployment topology, ยง Observability diff --git a/.planning/phase-1-telemetry/04-teltonika-framing.md b/.planning/phase-1-telemetry/04-teltonika-framing.md index 90caec0..79f2aae 100644 --- a/.planning/phase-1-telemetry/04-teltonika-framing.md +++ b/.planning/phase-1-telemetry/04-teltonika-framing.md @@ -1,7 +1,7 @@ # Task 1.4 โ€” Teltonika framing layer **Phase:** 1 โ€” Inbound telemetry -**Status:** โฌœ Not started +**Status:** ๐ŸŸฉ Done โ€” landed in commit `1e9219d` **Depends on:** 1.2 **Wiki refs:** `docs/wiki/concepts/avl-data-format.md` (envelope, IMEI handshake), `docs/wiki/concepts/codec-dispatch.md`, `docs/wiki/sources/teltonika-data-sending-protocols.md` diff --git a/.planning/phase-1-telemetry/05-codec-8.md b/.planning/phase-1-telemetry/05-codec-8.md index 1c2436e..0cdc3a9 100644 --- a/.planning/phase-1-telemetry/05-codec-8.md +++ b/.planning/phase-1-telemetry/05-codec-8.md @@ -1,7 +1,7 @@ # Task 1.5 โ€” Codec 8 parser **Phase:** 1 โ€” Inbound telemetry -**Status:** โฌœ Not started +**Status:** ๐ŸŸฉ Done โ€” landed in commit `381287b` **Depends on:** 1.4, 1.9 (fixture infra) **Wiki refs:** `docs/wiki/concepts/avl-data-format.md` ยง Codec 8, `docs/wiki/sources/teltonika-data-sending-protocols.md` ยง Codec 8 diff --git a/.planning/phase-1-telemetry/06-codec-8-extended.md b/.planning/phase-1-telemetry/06-codec-8-extended.md index 140fc1a..a746032 100644 --- a/.planning/phase-1-telemetry/06-codec-8-extended.md +++ b/.planning/phase-1-telemetry/06-codec-8-extended.md @@ -1,7 +1,7 @@ # Task 1.6 โ€” Codec 8 Extended parser **Phase:** 1 โ€” Inbound telemetry -**Status:** โฌœ Not started +**Status:** ๐ŸŸฉ Done โ€” landed in commit `381287b` **Depends on:** 1.4, 1.5 (shared GPS Element / timestamp helpers), 1.9 **Wiki refs:** `docs/wiki/concepts/avl-data-format.md` ยง Codec 8 Extended, `docs/wiki/sources/teltonika-data-sending-protocols.md` ยง Codec 8 Extended diff --git a/.planning/phase-1-telemetry/07-codec-16.md b/.planning/phase-1-telemetry/07-codec-16.md index c5387b4..97faaeb 100644 --- a/.planning/phase-1-telemetry/07-codec-16.md +++ b/.planning/phase-1-telemetry/07-codec-16.md @@ -1,7 +1,7 @@ # Task 1.7 โ€” Codec 16 parser **Phase:** 1 โ€” Inbound telemetry -**Status:** โฌœ Not started +**Status:** ๐ŸŸฉ Done โ€” landed in commit `381287b` **Depends on:** 1.4, 1.5 (shared helpers), 1.9 **Wiki refs:** `docs/wiki/concepts/avl-data-format.md` ยง Codec 16, `docs/wiki/sources/teltonika-data-sending-protocols.md` ยง Codec 16 diff --git a/.planning/phase-1-telemetry/08-redis-publisher.md b/.planning/phase-1-telemetry/08-redis-publisher.md index e43a9fd..ecb5688 100644 --- a/.planning/phase-1-telemetry/08-redis-publisher.md +++ b/.planning/phase-1-telemetry/08-redis-publisher.md @@ -1,7 +1,7 @@ # Task 1.8 โ€” Redis Streams publisher & main wiring **Phase:** 1 โ€” Inbound telemetry -**Status:** ๐ŸŸฉ Done +**Status:** ๐ŸŸฉ Done โ€” landed in commit `af06973` **Depends on:** 1.2, 1.3, 1.4, 1.5, 1.6, 1.7 **Wiki refs:** `docs/wiki/entities/redis-streams.md`, `docs/wiki/concepts/position-record.md` diff --git a/.planning/phase-1-telemetry/09-fixture-suite.md b/.planning/phase-1-telemetry/09-fixture-suite.md index 441c196..d8e3539 100644 --- a/.planning/phase-1-telemetry/09-fixture-suite.md +++ b/.planning/phase-1-telemetry/09-fixture-suite.md @@ -1,7 +1,7 @@ # Task 1.9 โ€” Fixture suite & testing strategy **Phase:** 1 โ€” Inbound telemetry -**Status:** โฌœ Not started +**Status:** ๐ŸŸฉ Done โ€” landed in commit `381287b` **Depends on:** 1.1 **Wiki refs:** `docs/wiki/sources/teltonika-ingestion-architecture.md` ยง 5.6, `docs/wiki/sources/teltonika-data-sending-protocols.md` diff --git a/.planning/phase-1-telemetry/10-observability.md b/.planning/phase-1-telemetry/10-observability.md index 80df9f8..063b8c0 100644 --- a/.planning/phase-1-telemetry/10-observability.md +++ b/.planning/phase-1-telemetry/10-observability.md @@ -1,7 +1,7 @@ # Task 1.10 โ€” Observability (Prometheus metrics) **Phase:** 1 โ€” Inbound telemetry -**Status:** โฌœ Not started +**Status:** โธ Paused โ€” deferred until after the real-device pilot test. See ROADMAP.md "Deferred" section for resume triggers. The placeholder `Metrics` interface in `src/core/types.ts` is what code currently uses; this task replaces it with `prom-client` and adds the `/metrics`, `/healthz`, `/readyz` HTTP endpoints. **Depends on:** 1.2, 1.3 **Wiki refs:** `docs/wiki/sources/teltonika-ingestion-architecture.md` ยง 7. Observability, `docs/wiki/sources/gps-tracking-architecture.md` ยง 7.4 diff --git a/.planning/phase-1-telemetry/12-production-hardening.md b/.planning/phase-1-telemetry/12-production-hardening.md index 1ba32ed..e278e69 100644 --- a/.planning/phase-1-telemetry/12-production-hardening.md +++ b/.planning/phase-1-telemetry/12-production-hardening.md @@ -1,7 +1,7 @@ # Task 1.12 โ€” Production hardening **Phase:** 1 โ€” Inbound telemetry -**Status:** โฌœ Not started +**Status:** โธ Paused โ€” deferred until after the real-device pilot test. See ROADMAP.md "Deferred" section for resume triggers. `installGracefulShutdown` exists as a stub from task 1.8; this task fully implements signal handling, drain timeouts, unhandled-rejection handlers, and writes OPERATIONS.md. **Resume before any always-on deployment or rolling-restart workflow.** **Depends on:** 1.8, 1.10, 1.11 **Wiki refs:** `docs/wiki/concepts/failure-domains.md` diff --git a/.planning/phase-1-telemetry/13-device-authority.md b/.planning/phase-1-telemetry/13-device-authority.md index 67910d2..a5a2cf5 100644 --- a/.planning/phase-1-telemetry/13-device-authority.md +++ b/.planning/phase-1-telemetry/13-device-authority.md @@ -1,7 +1,7 @@ # Task 1.13 โ€” Device authority (Redis allow-list refresher) **Phase:** 1 โ€” Inbound telemetry -**Status:** โฌœ Not started (deferrable โ€” can ship after the rest of Phase 1) +**Status:** โธ Paused โ€” deferred until after the real-device pilot test, AND until Directus has a `devices` collection publishing the allow-list to Redis. See ROADMAP.md "Deferred" section. The `DeviceAuthority` seam exists with `AllowAllAuthority` (default, in `src/adapters/teltonika/device-authority.ts`); this task adds `RedisAllowListAuthority`. **Depends on:** 1.4 (DeviceAuthority seam), 1.10 (metrics) **Wiki refs:** `docs/wiki/concepts/plane-separation.md`, `docs/wiki/entities/directus.md`, `docs/wiki/entities/redis-streams.md`