azaion/satellite-provider
1
0
Fork 0
mirror of https://github.com/azaion/satellite-provider.git synced 2026-06-21 09:51:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

[AZ-505] Test-spec sync + task-mode doc updates for cycle 6
ci/woodpecker/push/01-test Pipeline was successful
Details
ci/woodpecker/push/02-build-push Pipeline was successful
Details

Browse Source 
Step 12 (Test-Spec Sync, cycle-update mode):
- blackbox-tests.md: append BT-23..BT-26 for AZ-505's new
  observable behaviors (inventory order/shape; leaflet
  most-recent via location_hash; HTTP/2 multiplex over TLS+ALPN;
  request validation).
- performance-tests.md: append PT-09 (inventory p95 ≤ 1000ms /
  2500 tiles); records cycle-6 measured p95=66ms; documents
  promotion path to scripts/run-performance-tests.sh if budget
  ever tightens.
- traceability-matrix.md: resolve the 5 AZ-503 deferrals
  (AC-5/6/9/10/12) by pointing at AZ-505 test names + add 7
  AZ-505 AC rows (AC-1..AC-7) + bump totals (90 -> 94 tests,
  56/56 -> 63/63 in-scope) + add cycle-6 coverage shape notes
  (budget relaxation rationale, voting-filter deferral note,
  TLS+ALPN pivot, NFR propagation).

Step 13 (Update Docs, task mode):
- common_dtos.md: add 5 new TileInventory DTOs.
- common_interfaces.md: add ITileService.GetInventoryAsync.
- services_tile_service.md: document TileService.GetInventoryAsync
  steps + the XOR-validation-in-handler note.
- dataaccess_migrator.md: bump migration count 14 -> 15;
  describe migration 015 (AZ-505 leaflet covering index, lock
  window, INCLUDE-list trade-off).
- system-flows.md: add F7 (Leaflet Tile Serving, AZ-310 +
  AZ-505 location_hash rewire + TLS+ALPN) and F8 (Tile
  Inventory Bulk Lookup) with sequence diagrams, validation
  surface, and AC-4 perf evidence. Update Flow Inventory +
  Dependencies tables accordingly.
- glossary.md: add "Tile Inventory" entry pointing at the
  v1.0.0 contract.
- ripple_log_cycle6.md: new file — exhaustive reverse-dependency
  analysis confirms zero stale downstream module docs.

Advance autodev state from step 11 -> 14 (skipping 12+13 as
completed in this commit; auto-chain through Step 14 = Security
Audit optional gate).

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-12 22:29:22 +03:00
parent c74a2339aa
commit 5d84d2839e
11 changed files with 246 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files
_docs/02_document/tests/traceability-matrix.md
+23 -7
View File
@@ -93,11 +93,18 @@
| AZ-503 AC-7 | content_sha256 is computed and persisted; byte-identical bodies produce identical digest | BT-20 (blackbox); `UavTileUploadHandlerTests.HandleAsync_IdenticalUpload_ProducesIdenticalIdAndDeterministicContentSha` (unit) | ✓ |
| AZ-503 AC-8 | Migration 014 adds columns + supersedes AZ-484 index + backfills location_hash deterministically | BT-22 (blackbox); `MigrationTests.Az503ColumnsExistAndLocationHashIsNotNull`, `Az503NewUniqueIndexCoversIntegerKeyAndFlightId`, `Az503LocationHashBackfillIsDeterministic`, `Az503MigrationSupersedesAz484UniqueIndex` (integration) | ✓ |
| AZ-503 AC-11 | Per-flight on-disk separation (`./tiles/uav/{flight_id\|none}/{z}/{x}/{y}.jpg`) | BT-19 (blackbox); `UavTileFilePathTests.BuildUavTileFilePath_AnonymousFlight_UsesNoneSegment`, `_PerFlight_UsesFlightIdDirectory`, `_DifferentFlights_ProduceDifferentPaths` (unit); `UavUploadTests.MultiFlightUavRowsCoexist_AZ503_AC3` (integration; per-flight file_path assertion) | ✓ |
| AZ-503 AC-5 | Inventory endpoint `POST /api/satellite/tiles/inventory` returns one entry per requested coord | — | ◐ deferred → AZ-505 |
| AZ-503 AC-6 | Leaflet path returns most-recent variant via `location_hash` | — | ◐ deferred → AZ-505 |
| AZ-503 AC-9 | Inventory endpoint p95 ≤ 500 ms for 2500 tiles | — | ◐ deferred → AZ-505 (perf NFR) |
| AZ-503 AC-10 | Leaflet hot path is index-only (EXPLAIN: no heap fetch when `voting_status='trusted'`) | — | ◐ deferred → AZ-505 |
| AZ-503 AC-12 | HTTP/2 multiplexed responses for `/tiles/{z}/{x}/{y}` | — | ◐ deferred → AZ-505 |
| AZ-503 AC-5 | Inventory endpoint `POST /api/satellite/tiles/inventory` returns one entry per requested coord | BT-23 (blackbox); resolved by AZ-505 AC-1 — see row below | ✓ (via AZ-505) |
| AZ-503 AC-6 | Leaflet path returns most-recent variant via `location_hash` | BT-24 (blackbox); resolved by AZ-505 AC-2 — see row below | ✓ (via AZ-505) |
| AZ-503 AC-9 | Inventory endpoint p95 ≤ 500 ms for 2500 tiles | PT-09 (performance); resolved by AZ-505 AC-4 — see row below (budget relaxed to 1000 ms under AZ-505 scoping, AZ-505 Risk 1) | ✓ (via AZ-505, relaxed budget) |
| AZ-503 AC-10 | Leaflet hot path is index-only (EXPLAIN: no heap fetch when `voting_status='trusted'`) | Resolved by AZ-505 AC-3 — see row below (voting layer is deferred to a future task per AZ-505 Non-Goals; AC-3 verifies the index-only access path against `tiles_leaflet_path` directly via `EXPLAIN ANALYZE` + `Heap Fetches: 0` assertion) | ✓ (via AZ-505, voting-filter deferred) |
| AZ-503 AC-12 | HTTP/2 multiplexed responses for `/tiles/{z}/{x}/{y}` | BT-25 (blackbox); resolved by AZ-505 AC-5 — see row below | ✓ (via AZ-505) |
| AZ-505 AC-1 | Inventory endpoint returns one entry per requested coord in input order; present/absent shaping per `tile-inventory.md` Inv-1..Inv-6 | BT-23 (blackbox); `TileInventoryTests.OrderingAndPresentAbsentShaping_AC1` (integration) | ✓ |
| AZ-505 AC-2 | Leaflet read path returns most-recent variant keyed on `location_hash` (`captured_at DESC, updated_at DESC, id DESC LIMIT 1`) | BT-24 (blackbox); `TileInventoryTests.LeafletReadReturnsMostRecentViaLocationHash_AC2` (integration; DB-level verification of the exact SELECT used by `TileRepository.GetByTileCoordinatesAsync`, which `ServeTile` wraps unchanged) | ✓ |
| AZ-505 AC-3 | Leaflet hot path uses `Index Only Scan using tiles_leaflet_path`; `Heap Fetches` ≤ 1 after `VACUUM ANALYZE`; query time < 1 ms | `LeafletPathIndexOnlyTests.RunAll` (integration; `EXPLAIN ANALYZE` + regex + `Heap Fetches ≤ 1`; smoke run falls back to `SET enable_seqscan = off` if the optimiser hasn't picked the index naturally — measures index *capability*, not optimiser heuristic) | ✓ |
| AZ-505 AC-4 | Inventory endpoint p95 ≤ 1000 ms for 2500 tiles over 20 calls | PT-09 (performance); `TileInventoryTests.PerformanceBudget_AC4` (integration; full-suite only, smoke prints a documented skip). Cycle 6 measured: `p95=66ms, max=117ms` — well under budget. | ✓ |
| AZ-505 AC-5 | HTTP/2 multiplexed responses for `/tiles/{z}/{x}/{y}` over a single connection with preserved ETag + Cache-Control headers | BT-25 (blackbox); `Http2MultiplexingTests.RunAll` (integration; 20 concurrent GETs over a single TLS connection with `SocketsHttpHandler { EnableMultipleHttp2Connections = false }` + `HttpVersion.Version20` + `RequestVersionExact`). Implementation uses TLS+ALPN on the dev `https://+:8080` listener (cert generated by `scripts/run-tests.sh` into `./certs/api.pfx`, trusted in the integration-tests container via `update-ca-certificates`) — the original h2c plan was switched mid-cycle because Kestrel silently downgrades `Http1AndHttp2` to HTTP/1.1 over plaintext (no ALPN). See `_docs/03_implementation/implementation_report_tile_inventory_cycle6.md` → "Post-merge correction". | ✓ |
| AZ-505 AC-6 | Request validation — 400 on both populated, 400 on neither, 400 on > 5000 entries, 401 on anonymous | BT-26 (blackbox); `TileInventoryTests.ValidationRejectsBothPopulated_AC6`, `ValidationRejectsNeitherPopulated_AC6`, `ValidationRejectsOversizedBatch_AC6`, `UnauthenticatedRequestReturns401_AC6` (integration) | ✓ |
| AZ-505 AC-7 | Contract artifacts produced in the same commit as code (`tile-inventory.md` v1.0.0, `tile-storage.md` v2.0.0 Change Log, `module-layout.md` rows) | Doc inspection at completeness gate — `_docs/03_implementation/implementation_completeness_cycle6_report.md` "Files / Symbols Checked" + "Contracts" sections list the v1.0.0 / v2.0.0 artifacts; no runtime test (deliberately doc-only) | ✓ (doc-only) |
| AZ-504 AC-1 | PT-08 completes on zero-rejected response (no script exit under `set -e -o pipefail`) | Standalone shell harness (4-case) executed in batch_01_cycle5_report.md — accepted/rejected counters wrapped in `{ grep -o … \|\| true; }` at `scripts/run-performance-tests.sh:416-417`; structural: `rg "grep -o .* \\\| wc -l" scripts/run-performance-tests.sh` returns 0 unguarded sites | ✓ |
| AZ-504 AC-2 | PT-08 completes on zero-accepted response (defensive) | Same standalone shell harness (case 4) — `accepted=0, rejected=N` path no longer kills the script | ✓ |
| AZ-504 AC-3 | PT-08 summary line prints in full default-parameter perf run | Verified at autodev Step 15 (Performance Test) by running `scripts/run-performance-tests.sh` with `PERF_REPEAT_COUNT=20 PERF_UAV_BATCH_SIZE=10`; pass criterion is the `PT-08 UAV batch upload: PASS p95=Xms / 2000ms (...)` line in the run output | ◐ gate at Step 15 |
@@ -148,9 +155,10 @@
| Cycle 1 — AZ-484 (integration + unit) | 6 | 7/7 | — |
| Cycle 2 — AZ-487 (integration + unit + behavioral) | 4 integration + 3 unit + 1 behavioral | 8/8 | — |
| Cycle 2 — AZ-488 (integration + unit + blackbox) | 7 integration + 14 unit + 6 blackbox | 10/10 | — |
| Cycle 5 — AZ-503 foundation (integration + unit + blackbox) | 2 integration + 6 unit + 4 blackbox | 7/12 in-scope (AC-1, 2, 3, 4, 7, 8, 11); 5 ACs deferred → AZ-505 | — |
| Cycle 5 — AZ-503 foundation (integration + unit + blackbox) | 2 integration + 6 unit + 4 blackbox | 7/12 in-scope (AC-1, 2, 3, 4, 7, 8, 11); 5 ACs deferred → AZ-505 (now resolved in cycle 6) | — |
| Cycle 5 — AZ-504 perf-script fix (shell harness + Step-15 gate) | 1 standalone shell harness (4 cases) | 2/4 verified now (AC-1, AC-2); 2/4 gated at Step 15 (AC-3, AC-4) | — |
| **Total** | **90** | **56/56 in-scope (100%); 5 explicitly deferred to AZ-505 next cycle; 2 AZ-504 ACs gated at Step 15** | **8/8 (100%)** |
| Cycle 6 — AZ-505 inventory + HTTP/2 + leaflet covering index (integration + blackbox + perf) | 3 integration files + 4 blackbox (BT-23..BT-26) + 1 perf (PT-09) | 7/7 (AC-1..AC-7; AC-7 is doc-only). Also resolves the 5 AZ-503 deferrals (AC-5, 6, 9, 10, 12). | — |
| **Total** | **94** | **63/63 in-scope (100%); 2 AZ-504 ACs gated at Step 15** | **8/8 (100%)** |
**Coverage shape notes (Cycle 5 — AZ-503 foundation):**
- AZ-503 was split mid-cycle (Option C, autodev Step 10 batch 2): 7 of 12 original ACs land here; 5 (AC-5, AC-6, AC-9, AC-10, AC-12) are deferred to AZ-505 with a `Blocks` link in Jira and an entry in `_docs/02_tasks/_dependencies_table.md`. The deferred rows above are marked `◐ deferred → AZ-505` so the matrix surfaces the scope boundary explicitly.
@@ -170,3 +178,11 @@
- AZ-500 AC-5 (perf-script bootstrap) demoted the cycle-3 SDK-mismatch leftover to a script-bug leftover (PT-08 grep-pipefail at `scripts/run-performance-tests.sh:417`). The full PT-01..PT-08 perf gate moves to cycle 4 Step 15 (Performance Test). The PT-07 / PT-08 coverage rows above remain `✓` because they reflect the harness's *measurement capability*, not the per-cycle measurement run.
- AZ-500 NFRs (Compatibility / Performance / Reliability / Security) propagate to existing rows rather than introducing new gates: Compatibility ⇒ cycle-3 architecture-compliance baseline (verified by Step 11 suite); Performance ⇒ Step 15 perf gate (PT-07/PT-08); Reliability ⇒ no `dotnet restore` failures in the migrated state (Step 11 build path); Security ⇒ Step 14 dependency-scan re-run.
- Restriction "**.NET 8.0 runtime**" was rewritten to "**.NET 10 runtime**" — this is a supersession (toolchain bump) not a new gate, so no Choose was needed per cycle-update rule 3.
**Coverage shape notes (Cycle 6 — AZ-505 inventory + HTTP/2 + leaflet covering index):**
- AZ-505 resolves the five AZ-503 deferrals (AC-5, AC-6, AC-9, AC-10, AC-12) and adds two strictly new ACs (AC-6 request validation, AC-7 contract-artifacts-in-same-commit). The deferred AZ-503 rows above are rewritten from `◐ deferred → AZ-505` to `✓ (via AZ-505)` and now point at the cycle-6 test entries — the AZ-503 contract is preserved, the implementation just landed one cycle later.
- AZ-503 AC-9's original 500 ms p95 budget for 2500 tiles was relaxed to 1000 ms during AZ-505 scoping (AZ-505 Risk 1 documents the trade-off: the inventory result set projects columns beyond `tiles_leaflet_path`'s INCLUDE list, so a bounded heap fetch is unavoidable). The cycle-6 measured p95 is `66 ms` — 15× under the relaxed budget — so the relaxation is conservative, not load-bearing.
- AZ-503 AC-10 originally specified `Heap Fetches: 0 when voting_status='trusted'`. The voting layer is deferred to a future task per `tile-inventory.md` v1.0.0 Non-Goals (`voting / trust-promotion filtering`). AZ-505 AC-3 verifies the index-only access path against `tiles_leaflet_path` directly via `EXPLAIN ANALYZE` + `Heap Fetches ≤ 1` assertion, which is the AC-10 intent minus the voting filter. When voting lands, AC-10's `voting_status='trusted'` predicate will be re-verified by the voting task.
- AZ-505 AC-5 originally specified h2c (HTTP/2 over plaintext). Kestrel was switched to TLS+ALPN on `https://+:8080` during the cycle-6 Run Tests step because `HttpProtocols.Http1AndHttp2` silently downgrades to HTTP/1.1 over plaintext (no ALPN). The functional gate (multiplexing semantics) is unchanged — the test still asserts `HttpResponseMessage.Version == 2.0` over 20 concurrent GETs on a single connection. The deployment caveat (dev cert vs. production TLS termination at the ingress) is documented in `tile-inventory.md` Non-Goals.
- AZ-505 NFRs propagate as follows: Performance (AC-3, AC-4) ⇒ PT-09 entry (full PT-09 row in `performance-tests.md`); Compatibility (existing `GET /tiles/{z}/{x}/{y}` byte-identical) ⇒ no new test — the AZ-484 / AZ-503-foundation selection rule is unchanged, and the test that exercised it under the old `(z, x, y)`-keyed SELECT now exercises it under the `location_hash`-keyed SELECT via AC-2; Security (JWT + `RequireAuthorization()`) ⇒ AC-6 anonymous-401 case, BT-26.
- Cycle-update rule check: no NFR conflicts surfaced. The 500 ms → 1000 ms perf budget relaxation between AZ-503 AC-9 and AZ-505 AC-4 is **not** a conflict in the cycle-update sense — AZ-503 AC-9 was explicitly deferred (`◐ deferred → AZ-505`) so AZ-505 owns the binding budget; AZ-503's number was a pre-implementation estimate. The matrix records both numbers and the rationale so the budget history stays auditable.