Phase 18: respect buf.yaml dependency refs + prewarm removal

.planning/ROADMAP.md

@@ -169,6 +169,26 @@ Plans:
 | 15. Operational Logging       | v1.3 | 0/0 | Not started | - |
 | 16. Commit ID Resolution Improvements | v1.3 | 3/3 | Complete    | 2026-07-06 |
 | 17. Fix PR #37 review findings | v1.3 | 1/1 | Complete | 2026-07-07 |
+| 18. Respect buf.yaml dependency refs (not always HEAD); fix related bug; remove prewarm logic | v1.3 | 1/1 | Complete | 2026-07-07 |
+
+### Phase 18: Respect buf.yaml dependency refs (not always HEAD); fix related bug; remove prewarm logic now that buf id → git id is derivable
+
+**Goal:** Three corrections to dependency resolution, shipped as one atomic pass: (1) honor the `ref` field the buf CLI sends in the `Name` message so a dep like `cyp/cyp-net-listeners:main/v2` returns the SHA at `main/v2`, not the HEAD; (2) replace the `commit != "" && commit != "main"` short-circuit in both bitbucket and github providers with an `isSHA(commit)` gate so non-SHA inputs route through the providers' commit-fetch APIs to resolve; (3) drop the `prewarmHeads` startup fan-out and replace it with a UUID→SHA-prefix inverse function (`commitUUIDInverse`) that lets `probeCommitID` recover the right module on a Download cache-miss without the prewarm.
+**Depends on:** Phase 17
+**Requirements**: SC-1, SC-2, SC-3, SC-4, SC-5
+**Success Criteria** (what must be TRUE):
+
+  1. A buf client pinning `buf-proxy.yadro.dev/cyp/cyp-net-listeners:main/v2` in `buf.yaml` gets a UUID in `buf.lock` derived from the SHA at `main/v2` (not from HEAD) — verified end-to-end by the providers' `TestGetMeta_ResolvesRef` and the connect-package `TestParseResourceRefName_ReadsRef`
+  2. The `commit != "" && commit != "main"` short-circuit is gone from both `bitbucket/getrepo.go` and `github/getrepo.go`; both providers now gate on `isSHA(commit)` — verified by structural grep + `go test ./internal/providers/{bitbucket,github}/ -count=1`
+  3. `prewarmHeads` and `registerResolved` are deleted from `commits.go`; the goroutine launch in `api.go:111-113` is gone; the `PrewarmConfig` block in `config.go:96-101` is gone; `prewarmEnabled`/`prewarmTimeout`/`prewarmOnce` fields on `commitServiceHandler` and `PrewarmEnabled`/`PrewarmTimeout` on `CommitResolution` are gone — verified by 5 structural grep checks returning 0 hits
+  4. `commitUUIDInverse(uuid string) (string, error)` exists in `commits_helpers.go`, returns the 28-char SHA prefix, errors on non-32-char or non-hex input; `TestCommitUUIDInverse` covers 8 cases (round-trip with a known 40-char SHA, all-zero, all-ones, 64-char SHA round-trip, empty, 31-char, 33-char, 32-char non-hex)
+  5. `probeCommitID` derives the 28-char SHA prefix from a 32-char UUID input via `commitUUIDInverse`, probes each source with the prefix, and only registers a hit when the returned `meta.Commit` actually starts with the recovered prefix (collision-safe); `TestServeDownload_AfterRestart_ProbeResolvesUUID` and `TestServeDownload_AfterRestart_ProbeMissesOnUnknownUUID` exercise the post-restart path
+
+**Plans:** 1 plan
+Plans:
+Plans:
+
+- [x] [18-01](./phases/18-respect-buf-yaml-dependency-refs-not-always-head-fix-related/18-01-PLAN.md) — Honor `Name.ref` end-to-end + isSHA-gated provider ref-resolution + prewarm removal with `commitUUIDInverse`-based probe
 
 ---
 

.planning/STATE.md

@@ -2,14 +2,14 @@
 gsd_state_version: 1.0
 milestone: v1.3
 milestone_name: Diagnostic Logging — In Progress
-status: shipped
-last_updated: "2026-07-07T10:32:00.000Z"
-last_activity: 2026-07-07 -- Phase 17 shipped (review fixes posted as PR #37 comment)
+status: executing
+last_updated: "2026-07-07T14:17:36.053Z"
+last_activity: 2026-07-07 -- Phase 18 planning complete
 progress:
-  total_phases: 7
-  completed_phases: 7
-  total_plans: 9
-  completed_plans: 9
+  total_phases: 8
+  completed_phases: 8
+  total_plans: 10
+  completed_plans: 10
   percent: 100
 ---
 
@@ -25,27 +25,28 @@ See: .planning/PROJECT.md (updated 2026-05-10)
 
 ## Current Position
 
-Phase: 17
-Plan: 17-01 shipped
-Status: Phase 17 shipped — review fixes posted as comment on PR #37
-Last activity: 2026-07-07 -- Phase 17 shipped (PR #37 comment <https://github.com/easyp-tech/server/pull/37#issuecomment-4901262336>)
+Phase: 18
+Plan: 18-01 shipped
+Status: Phase 18 plan 01 complete
+Last activity: 2026-07-07 -- Phase 18 plan 01 execution complete (refs, isSHA, prewarm removal, commitUUIDInverse)
 
 Progress: [####################] 100%
 
 ## Performance Metrics
 
 **Velocity:**
 
-- Total plans completed: 4 (this milestone)
-- Average duration: ~8 min
-- Total execution time: ~32 min
+- Total plans completed: 5 (this milestone)
+- Average duration: ~10 min
+- Total execution time: ~50 min
 
 **By Phase:**
 
 | Phase | Plans | Total | Avg/Plan |
 |-------|-------|-------|----------|
 | 16    | 3     | -     | -        |
 | 17    | 1     | -     | 8 min    |
+| 18    | 1     | -     | 18 min   |
 
 **Recent Trend:**
 
@@ -76,6 +77,8 @@ None yet.
 
 - Phase 16 added: предлагаю изменения — use first 16 bytes of git commit id, probe all repos on miss, fix unclear not-found error message
 - Phase 17 added: Fix PR #37 review findings — address pre-merge issues from Phase 16 PR: re-route digest errors through `logHandlerError`/`upstreamError` (not `internalError`), remove `internalError` helper that bypassed `ERR-05`, accept SHA-256 Bitbucket commits (regression at commits_helpers.go:39), move `preResolveForTest` to a `_test.go` file
+- Phase 18 added: respect buf.yaml dependency refs (not always HEAD); fix related bug; remove prewarm logic now that buf id → git id is derivable
+- Phase 18 planned: 1 plan (18-01-PLAN.md) with 3 tasks — (1) honor `Name.ref` end-to-end + add `isSHA`/`isUUID`/`commitUUIDInverse` helpers + provider ref-resolution; (2) add `commitUUIDInverse` + table-driven tests; (3) delete `prewarmHeads`/`registerResolved`/`PrewarmConfig` and rewrite `probeCommitID` to use the inverse for 32-char UUID inputs. See `.planning/phases/18-respect-buf-yaml-dependency-refs-not-always-head-fix-related/18-{RESEARCH,01-PLAN,VALIDATION}.md`
 
 ## Deferred Items
 
@@ -89,6 +92,6 @@ Items acknowledged and carried forward from previous milestone close:
 
 ## Session Continuity
 
-Last session: 2026-07-07T10:32:00.000Z
-Stopped at: Phase 17 shipped (1/1 plan, 4 tasks, 5 SCs satisfied, 13/13 verified, comment posted on PR #37)
-Resume file: <https://github.com/easyp-tech/server/pull/37#issuecomment-4901262336>
+Last session: 2026-07-07T14:17:36Z
+Stopped at: Phase 18 shipped (1/1 plan, 3 tasks, 5 SCs satisfied, executor self-check PASSED, 18 min)
+Resume file: `.planning/phases/18-respect-buf-yaml-dependency-refs-not-always-head-fix-related/18-01-SUMMARY.md`