fix(pull): state-aware findExistingResourceId — prevent same-name clobber

[dhruva-reddy]

Summary

pull's findExistingResourceId helper used to silently clobber an existing-tracked resource's file + state mapping whenever the dashboard had a second resource with the same name. The 1:1 name-slug match guard intended for cross-environment adoption ("dev's file with a different UUID-suffix — reuse it for the prod resource of the same name") didn't distinguish between "this on-disk file is free for adoption" vs "this file is already tracked in state by a DIFFERENT UUID."

The fix makes the function state-aware: it consults the merged view of prior-pull state + in-flight pull state to decide whether each candidate file is adoptable. Files already claimed by a different UUID are NOT adoptable — the caller falls through to generateResourceId(resource) which produces a deterministic <name>-<uuid8>.md slug per UUID.

Discovered in the gitops-mudflap customer working session 2026-05-13 (PRISM-737-adjacent) while investigating duplicate-resource accumulation.

What changes (behavior)

Scenario	Before	After
Single resource, single file on disk	Reuses file	Unchanged ✓
Cross-env pull: state empty, file exists with diff UUID-suffix	Reuses file (adoption)	Unchanged ✓
Re-pull of known UUID (reverseMap hit)	Reuses via reverseMap (this function not called)	Unchanged ✓
2 same-name dashboard resources, state has A's UUID, B is new	CLOBBER: B's content overwrites A's file, A's state mapping is lost	B gets new <name>-<bUuid8>.md; A stays intact ✓
N+ matches without a single adoptable candidate	Returns undefined (0-or-2+ ambiguity guard)	Unchanged ✓

Files changed

File	Change	LOC
src/pull.ts	findExistingResourceId promoted to export function, new stateSection arg + adoption filter; caller updated to pass {...state[resourceType], ...newStateSection}	~45
tests/find-existing-resource-id.test.ts	New file. 9 unit tests covering: cross-env adoption (regression), re-pull-same-UUID adoption, refusal-on-different-UUID claim (fix core), mixed-claim-with-1-adoptable adopt, N+ unclaimed → undefined, N+ all-claimed → undefined, name-absent, no-name-match, two-unclaimed-ambiguity	~190
tests/pull-same-name-clobber.test.ts	New file. Spawn-fixture integration test with parameterized dashboard-response ordering — both A-first AND B-first orderings asserted, since the reviewer caught that the initial single-state-section fix was iteration-order-dependent	~290

Test plan

• npm run build — clean
• npm test — 167/167 pass (156 prior + 11 new: 9 unit + 2 integration with parameterized ordering)
• npx @biomejs/biome check --write — clean

Code review

Reviewed twice during development. First pass surfaced a BLOCKING finding: the initial fix consulted only newStateSection, making it iteration-order-dependent. If the dashboard returned the new twin BEFORE the tracked one, newStateSection was empty when the new twin was processed, and the clobber happened anyway. Second commit on this branch (697a8dc) addresses that by merging state[resourceType] (prior-pull claims) into the adoption guard's view.

The B-first integration test in this PR fails on the first commit (d7c718f) and passes on the second (697a8dc) — it's the regression guard for the H1 finding.

Residual notes (non-blocking)

• credentials state section is not consulted by this function — credentials follow a different reverse-map flow in pullCredentials. Not relevant to this fix.
• No unparseable-claim defensive handling. ResourceState.uuid is typed string (non-optional). The filter checks claim === undefined || claim === resource.id. An empty-string uuid is theoretical and would block adoption (a strictly safer outcome than clobber). Not worth special-casing.
• Function name unchanged. findExistingResourceId is now a findAdoptableResourceId by behavior, but the existing name is recognizable and the docstring is updated. Renaming would churn the diff for no behavioral win.

Related

• VapiAI/gitops PR fix: dedup dependency auto-apply to prevent duplicate tool mints (Gap #10) #23 (gitops-side name dedup, merged 2026-05-10)
• VapiAI/gitops PR feat: npm run audit — read-only drift detector for state/dashboard divergence #27 (npm run audit command, merged 2026-05-13)
• VapiAI/gitops PR docs(agents): add npm run audit to AGENTS.md command tables #28 (AGENTS.md update, merged 2026-05-13)
• Linear PRISM-737 (vapi-core platform-side investigation, ongoing)