gitea_admin/sientia-dataops-opc-ingestor
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

SIENTIAPDE-1972: plano - modelo de PR por fase + ledger de commits (F0 registrado) + close-out por fase

Browse Source
This commit is contained in:
PedroHMCosme
2026-07-14 10:37:09 -03:00
parent b57be9f5fe
commit 00f919cec6
1 changed files with 70 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
docs/superpowers/plans/2026-07-13-opc-gateway.md
View File

@@ -46,6 +46,41 @@
---
## Phase Delivery & Commit Ledger
**Delivery model: one PR per phase (F0…F4), opened only at the very end.** To avoid one giant PR, each phase is delivered and reviewed as its own PR. But **no PR is opened until every phase is complete, tested, and working** — we build all phases on this feature branch first, then split them into per-phase PRs at the end. This section is the ledger that makes that split possible.
### Phase close-out (the LAST task of every phase — Tasks 7.end, 10.end, 13.end, 16.end, 21.end)
At the end of each phase Fx, before starting the next:
1. Confirm the phase is green: full `python -m pytest tests -v` passes and `ruff check ingestor tests` is clean.
2. Record the phase's commit SHAs (in order) in the ledger below, with the phase's base (parent of its first commit).
3. **Do NOT open the PR yet** — PRs are opened only after F4 closes (see "Final: open per-phase PRs").
### Commit ledger
**F0 — Connection core** — base `498030d` (merge-base with `main`). Status: ✅ complete, 162 unit tests green, ruff clean.
- `0694f6a` chore(gateway): add nats-py, grpcio deps (Task 1)
- `3dd4f60` feat(gateway): add write/active-read/error metrics (Task 2)
- `55f6721` feat(gateway): safe type converter (1879 BUG-1/BUG-2) (Task 3)
- `d6cb1e4` feat(gateway): monotonic clock helper (1879) (Task 4)
- `b05c2fd` feat(gateway): Basic256Sha256 + channel>session lifetime (1879) (Task 5)
- `ec2a324` feat(gateway): cert provider from MinIO+Mongo (sientia-dataops) (Task 6)
- `5d30a5c` feat(gateway): OpcConnectionPool (per-server, reuse, idle-evict) (Task 7)
- `0b29857` fix(gateway): per-server lock in OpcConnectionPool to avoid duplicate connects (Task 7)
- `b57be9f` refactor(gateway): drop dead error_stack and unused metadata from OpcConnectionPool (ponytail) (Task 7)
- Also fixed a pre-existing test flake in `a08fd88` (gc.collect() in test_ingestor_manager) — include in the F0 code PR.
- ⚠️ The branch also carries **docs** commits (design/spec/plan) interleaved in time (`6f6f3bf`, `c980092`, `524f4d6`, `8a05ff7`, `941c6c0`, `7cffc26`, `bbe10a4`, `09e4290`, plus the gRPC/Kafka doc updates). Those are **not** F0 code — the aig-docs equivalents already ship in PR #76; the repo `docs/superpowers/**` commits can go in a separate small docs PR or ride with F0. Keep them out of the F0 **code** PR scope.
**F1 — Subscription reads (C1):** _(fill at F1 close-out)_
**F2 — Active write via NATS (C2, C3):** _(fill at F2 close-out)_
**F3 — Active reads + gRPC (C4):** _(fill at F3 close-out)_
**F4 — Wiring, health, deploy, hardening:** _(fill at F4 close-out)_
### Final: open per-phase PRs (only after F4 is complete, tested, working)
Since all phases live on one feature branch, split them at the end using the recorded SHA ranges: for each phase in order F0→F4, create a phase branch off `main` (or stacked on the previous phase branch) containing only that phase's code commits (cherry-pick the ledger's SHA range), then open one PR per phase targeting `main`, in phase order. This keeps each PR small and reviewable instead of one giant diff.
---
## Phase F0 — Foundations (deps, config, metrics, connection pool)
### Task 1: Add dependencies
@@ -419,6 +454,13 @@ async def test_get_reuses_connection_per_server(monkeypatch):
---
### Task 7.end: F0 close-out (see [Phase Delivery](#phase-delivery--commit-ledger))
- [x] Full `pytest tests` green + `ruff` clean (162 passed).
- [x] F0 commits recorded in the [Commit Ledger](#commit-ledger).
- [ ] PR intentionally NOT opened yet — opened only after F4 closes.
---
## Phase F1 — Subscription reads with multi-name fan-out (contract C1)
### Task 8: Slot v2 loader
@@ -540,6 +582,13 @@ async def test_datachange_fans_out():
---
### Task 10.end: F1 close-out (see [Phase Delivery](#phase-delivery--commit-ledger))
- [ ] Full `pytest tests` green + `ruff` clean.
- [ ] Record F1 commit SHAs (base + range) in the [Commit Ledger](#commit-ledger).
- [ ] Do NOT open the PR yet.
---
## Phase F2 — Active write via NATS (contracts C2, C3)
### Task 11: WriteEngine
@@ -668,6 +717,13 @@ async def test_bad_json_does_not_raise():
---
### Task 13.end: F2 close-out (see [Phase Delivery](#phase-delivery--commit-ledger))
- [ ] Full `pytest tests` green + `ruff` clean.
- [ ] Record F2 commit SHAs (base + range) in the [Commit Ledger](#commit-ledger).
- [ ] Do NOT open the PR yet.
---
## Phase F3 — Active reads: scheduled + on-demand gRPC (contract C4)
### Task 14: ActiveReadEngine
@@ -764,6 +820,13 @@ async def test_readtag_maps_response():
---
### Task 16.end: F3 close-out (see [Phase Delivery](#phase-delivery--commit-ledger))
- [ ] Full `pytest tests` green + `ruff` clean.
- [ ] Record F3 commit SHAs (base + range) in the [Commit Ledger](#commit-ledger).
- [ ] Do NOT open the PR yet.
---
## Phase F4 — Wiring, health, deploy, hardening
### Task 17: Config additions
@@ -824,6 +887,13 @@ async def test_readtag_maps_response():
---
### Task 21.end: F4 close-out + open per-phase PRs (see [Phase Delivery](#phase-delivery--commit-ledger))
- [ ] Full `pytest tests` green + `ruff` clean; all F0–F4 phases complete, tested, working.
- [ ] Record F4 commit SHAs (base + range) in the [Commit Ledger](#commit-ledger).
- [ ] **Now** open one PR per phase (F0→F4) from the recorded SHA ranges, in order — this is the only point where PRs are opened.
---
## Deferred / out of this plan (tracked in spec §17)
- NATS provisioning in air-gapped Helm (platform).
- Moving 1569 cert write path to `sientia-dataops` (platform + 1569 app).