refactor: state schema with per-resource content hashes (#19)

## ELI5

**Problem.** The state file (`.vapi-state.<env>.json`) used to map
*name → UUID* and nothing else. So when push went to update a resource,
the engine had no way to tell whether someone had edited the resource
on the dashboard since you last pulled — there was nothing to compare
to. This is the root cause of "drift detection isn't possible," "real
rollback isn't possible," and "scoped pushes can't be precise about
what they touched": the engine has no per-resource memory of *what
was there before*.

**What this fix does.** Widens each state entry from a bare `string`
(the UUID) to a `ResourceState` object carrying:

  - `uuid`               — the platform UUID (unchanged semantics)
  - `lastPulledHash`     — sha256 of the platform payload at last pull
  - `lastPulledAt`       — ISO timestamp
  - `lastPushedHash`     — sha256 of the last pushed payload
  - `platformVersionId`  — Stack I, populated when platform exposes one

Every state-reading and state-writing call site is updated. **No new
external behavior ships in this PR alone** — strictly plumbing.
Backwards compatible: legacy state files (the old `string` shape) load
fine, just without hashes until the next pull/push populates them. The
on-disk file isn't rewritten until the next `saveState`, so a "deploy
and immediately rollback" doesn't corrupt state.

**Outcome you'll notice.** This PR alone changes nothing visible. It's
the architectural foundation that **drift detection (Stack G), snapshot
rollback (Stack H), and scoped state writes (Stack J)** all depend on.
After it lands, your next pull populates `lastPulledHash` for every
resource, and the next three PRs unlock real safety guarantees.

---

Architectural pivot. State sections move from Record<string, string>
(name → UUID) to Record<string, ResourceState> carrying:
  - uuid: string (the platform UUID, unchanged semantics)
  - lastPulledHash?: string (sha256 of canonicalized platform payload)
  - lastPulledAt?: string (ISO timestamp)
  - lastPushedHash?: string (sha256 of last pushed payload)
  - platformVersionId?: string (Stack I — populated when platform exposes one)

This is the architectural prerequisite for drift detection (Stack G),
snapshot rollback (Stack H), optimistic concurrency (Stack I), and scoped
state writes (Stack J). Every state-reading call site is updated, but
NO new external behavior ships in this PR — strictly plumbing.

Backwards compatibility:
- src/state.ts:loadState wraps any legacy bare-string value as
  { uuid: <string> } at load time. Existing customer state files keep
  working until their next pull populates hashes. No flag-day migration.
- The on-disk file is NOT rewritten until the next saveState, so a
  "deploy and immediately rollback" scenario does NOT corrupt state.

Files:
- src/types.ts: ResourceState type, StateFile sections retyped.
- src/state-serialize.ts: hashPayload (canonicalize + sha256),
  asResourceState (legacy migration), upsertState (preserves un-touched
  fields when patching).
- src/state.ts: stateUuid helper for the common case;
  loadState wraps legacy string entries via migrateSection;
  re-exports the helpers for ergonomics.
- src/pull.ts: each pull populates lastPulledHash + lastPulledAt;
  credential entries preserve prior metadata when slug+uuid are stable.
- src/push.ts: each PATCH/POST populates lastPushedHash via upsertState.
  All `state.X[id]` reads → `?.uuid`. State assignments → upsertState.
- src/cleanup.ts, src/credentials.ts, src/delete.ts, src/eval.ts,
  src/resolver.ts, src/call.ts: mechanical updates for the new shape.
  Verified by tsc — no leaks where a bare string is still expected.
- tests/state-migration.test.ts: legacy string entries load and
  round-trip; mixed legacy + new entries; canonicalize stability;
  hashPayload determinism; upsertState preservation semantics.

Closes improvements.md #4 (architectural prerequisite). G/H/I/J unblocked.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: dhruva-vapi

improvements.md

@@ -55,7 +55,7 @@ you which stack PR closes the row.**
 | 1   | `push` drift detection                                   | Prevent silent overwrites of dashboard edits       | #4         | Open (Stack G planned)            |
 | 2   | `apply` same-file conflict                               | `apply` drops concurrent same-file dashboard edits | #4         | Open (Stack G planned)            |
 | 3   | Rollback                                                 | Current undo can clobber newer live changes        | #4, #5     | Open (Stack H planned)            |
-| 4   | State schema content hashes                              | Architectural unlock for #1, #2, #3, #6, #7        | None       | Open (Stack F planned)            |
+| 4   | State schema content hashes                              | Architectural unlock for #1, #2, #3, #6, #7        | None       | RESOLVED 2026-04-30 (Stack F)     |
 | 5   | `push --dry-run`                                         | Cheapest operator-safety win                       | None       | RESOLVED 2026-04-30 (Stack C)     |
 | 6   | API-level optimistic concurrency                         | Server-side conflict rejection                     | Platform   | Deferred (Stack I, gated)         |
 | 7   | Voice edits drop pronunciation-dictionary attachments    | Silent regression on Cartesia + 11labs voice edits | #4         | Open (Stack G planned)            |

src/call.ts

@@ -292,9 +292,8 @@ function resolveTarget(
   resourceType: ResourceType,
 ): string {
   if (resourceType === "squad") {
-    const squads =
-      (state as StateFile & { squads?: Record<string, string> }).squads || {};
-    const uuid = squads[target];
+    const squads = state.squads || {};
+    const uuid = squads[target]?.uuid;
     if (!uuid) {
       console.error(`❌ Squad not found: ${target}`);
       console.error("   Available squads:");
@@ -308,7 +307,7 @@ function resolveTarget(
     }
     return uuid;
   } else {
-    const uuid = state.assistants[target];
+    const uuid = state.assistants[target]?.uuid;
     if (!uuid) {
       console.error(`❌ Assistant not found: ${target}`);
       console.error("   Available assistants:");

src/cleanup.ts

@@ -111,16 +111,18 @@ async function main(): Promise<void> {
   }
 
   const state = loadState();
+  // Stack F: state values are ResourceState objects, not bare UUIDs. Extract
+  // each .uuid for the orphan-detection set.
   const stateIds = new Set([
-    ...Object.values(state.assistants),
-    ...Object.values(state.tools),
-    ...Object.values(state.structuredOutputs),
-    ...Object.values(state.squads),
-    ...Object.values(state.personalities),
-    ...Object.values(state.scenarios),
-    ...Object.values(state.simulations),
-    ...Object.values(state.simulationSuites),
-    ...Object.values(state.evals),
+    ...Object.values(state.assistants).map((e) => e.uuid),
+    ...Object.values(state.tools).map((e) => e.uuid),
+    ...Object.values(state.structuredOutputs).map((e) => e.uuid),
+    ...Object.values(state.squads).map((e) => e.uuid),
+    ...Object.values(state.personalities).map((e) => e.uuid),
+    ...Object.values(state.scenarios).map((e) => e.uuid),
+    ...Object.values(state.simulations).map((e) => e.uuid),
+    ...Object.values(state.simulationSuites).map((e) => e.uuid),
+    ...Object.values(state.evals).map((e) => e.uuid),
   ]);
 
   // A state file with zero tracked resources is almost always a fresh clone,

src/credentials.ts

@@ -16,16 +16,16 @@ import type { StateFile } from "./types.ts";
 
 export function credentialReverseMap(state: StateFile): Map<string, string> {
   const map = new Map<string, string>();
-  for (const [name, uuid] of Object.entries(state.credentials)) {
-    map.set(uuid, name);
+  for (const [name, entry] of Object.entries(state.credentials)) {
+    map.set(entry.uuid, name);
   }
   return map;
 }
 
 export function credentialForwardMap(state: StateFile): Map<string, string> {
   const map = new Map<string, string>();
-  for (const [name, uuid] of Object.entries(state.credentials)) {
-    map.set(name, uuid);
+  for (const [name, entry] of Object.entries(state.credentials)) {
+    map.set(name, entry.uuid);
   }
   return map;
 }

src/delete.ts

@@ -3,6 +3,7 @@ import { FORCE_DELETE } from "./config.ts";
 import { extractReferencedIds } from "./resolver.ts";
 import type {
   ResourceFile,
+  ResourceState,
   StateFile,
   LoadedResources,
   OrphanedResource,
@@ -15,13 +16,13 @@ import type {
 
 export function findOrphanedResources(
   loadedResourceIds: string[],
-  stateResourceIds: Record<string, string>
+  stateResourceIds: Record<string, ResourceState>
 ): OrphanedResource[] {
   const orphaned: OrphanedResource[] = [];
 
-  for (const [resourceId, uuid] of Object.entries(stateResourceIds)) {
+  for (const [resourceId, entry] of Object.entries(stateResourceIds)) {
     if (!loadedResourceIds.includes(resourceId)) {
-      orphaned.push({ resourceId, uuid });
+      orphaned.push({ resourceId, uuid: entry.uuid });
     }
   }
 

src/eval.ts

@@ -250,10 +250,13 @@ function loadVariables(config: EvalConfig): Record<string, unknown> | undefined
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
-function resolveId(id: string, stateSection: Record<string, string>): string {
+function resolveId(
+  id: string,
+  stateSection: Record<string, { uuid: string } | undefined>,
+): string {
   const clean = id.split("##")[0]?.trim() ?? "";
   if (UUID_RE.test(clean)) return clean;
-  return stateSection[clean] ?? clean;
+  return stateSection[clean]?.uuid ?? clean;
 }
 
 function resolveAssistantConfig(config: Record<string, unknown>, state: StateFile): Record<string, unknown> {
@@ -278,7 +281,9 @@ function resolveAssistantConfig(config: Record<string, unknown>, state: StateFil
     }
   }
   // Resolve credentials
-  const credMap = new Map(Object.entries(state.credentials));
+  const credMap = new Map(
+    Object.entries(state.credentials).map(([slug, rs]) => [slug, rs.uuid]),
+  );
   if (credMap.size > 0) return deepReplace(resolved, credMap) as Record<string, unknown>;
   return resolved;
 }
@@ -314,7 +319,9 @@ async function resolveSquadConfig(config: Record<string, unknown>, state: StateF
       }
     }
   }
-  const credMap = new Map(Object.entries(state.credentials));
+  const credMap = new Map(
+    Object.entries(state.credentials).map(([slug, rs]) => [slug, rs.uuid]),
+  );
   if (credMap.size > 0) return deepReplace(resolved, credMap) as Record<string, unknown>;
   return resolved;
 }
@@ -344,9 +351,9 @@ function loadEvals(state: StateFile, filter?: string): EvalDefinition[] {
   const evalState = state.evals ?? {};
   const evals: EvalDefinition[] = [];
 
-  for (const [resourceId, uuid] of Object.entries(evalState)) {
+  for (const [resourceId, entry] of Object.entries(evalState)) {
     if (filter && !resourceId.toLowerCase().includes(filter.toLowerCase())) continue;
-    evals.push({ resourceId, evalId: uuid, name: resourceId });
+    evals.push({ resourceId, evalId: entry.uuid, name: resourceId });
   }
 
   return evals;
@@ -443,7 +450,7 @@ async function main(): Promise<void> {
 
   if (config.squadName) {
     if (config.useStored) {
-      const squadId = state.squads[config.squadName];
+      const squadId = state.squads[config.squadName]?.uuid;
       if (!squadId) {
         console.error(`❌ Squad not found in state: ${config.squadName}`);
         console.error("   Available: " + Object.keys(state.squads).join(", "));
@@ -466,7 +473,7 @@ async function main(): Promise<void> {
     }
   } else {
     if (config.useStored) {
-      const assistantId = state.assistants[config.assistantName!];
+      const assistantId = state.assistants[config.assistantName!]?.uuid;
       if (!assistantId) {
         console.error(`❌ Assistant not found in state: ${config.assistantName}`);
         process.exit(1);

src/pull.ts

@@ -15,9 +15,9 @@ import {
   loadIgnorePatterns,
   matchesIgnore,
 } from "./config.ts";
-import { loadState, saveState } from "./state.ts";
+import { hashPayload, loadState, saveState, upsertState } from "./state.ts";
 import { credentialReverseMap, replaceCredentialRefs } from "./credentials.ts";
-import type { StateFile, ResourceType } from "./types.ts";
+import type { ResourceState, StateFile, ResourceType } from "./types.ts";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types
@@ -221,11 +221,11 @@ async function pullCredentials(state: StateFile): Promise<void> {
   const credentials = await fetchCredentials();
   console.log(`   Found ${credentials.length} credentials in Vapi`);
 
-  const newSection: Record<string, string> = {};
+  const newSection: Record<string, ResourceState> = {};
   // Build reverse map from existing state to preserve slug stability
   const existingReverse = new Map<string, string>();
-  for (const [slug, uuid] of Object.entries(state.credentials)) {
-    existingReverse.set(uuid, slug);
+  for (const [slug, entry] of Object.entries(state.credentials)) {
+    existingReverse.set(entry.uuid, slug);
   }
 
   for (const cred of credentials) {
@@ -234,7 +234,12 @@ async function pullCredentials(state: StateFile): Promise<void> {
     if (!slug) {
       slug = credentialSlug(cred);
     }
-    newSection[slug] = cred.id;
+    // Preserve existing hash metadata if the slug+uuid pair survives.
+    const prior = state.credentials[slug];
+    newSection[slug] =
+      prior && prior.uuid === cred.id
+        ? prior
+        : { uuid: cred.id, lastPulledAt: new Date().toISOString() };
     console.log(`   🔑 ${slug} -> ${cred.id}`);
   }
 
@@ -327,12 +332,12 @@ function findExistingResourceId(
 }
 
 function removeUuidMappings(
-  stateSection: Record<string, string>,
+  stateSection: Record<string, ResourceState>,
   uuid: string,
   keepResourceId?: string,
 ): void {
-  for (const [resourceId, mappedUuid] of Object.entries(stateSection)) {
-    if (mappedUuid === uuid && resourceId !== keepResourceId) {
+  for (const [resourceId, entry] of Object.entries(stateSection)) {
+    if (entry.uuid === uuid && resourceId !== keepResourceId) {
       delete stateSection[resourceId];
     }
   }
@@ -368,8 +373,8 @@ function buildReverseMap(
   const map = new Map<string, string>();
   const stateSection = state[resourceType];
 
-  for (const [resourceId, uuid] of Object.entries(stateSection)) {
-    map.set(uuid, resourceId);
+  for (const [resourceId, entry] of Object.entries(stateSection)) {
+    map.set(entry.uuid, resourceId);
   }
 
   return map;
@@ -653,7 +658,7 @@ export async function pullResourceType(
 
   const reverseMap = buildReverseMap(state, resourceType);
   const credReverse = credentialReverseMap(state);
-  const newStateSection: Record<string, string> = resourceIds?.length
+  const newStateSection: Record<string, ResourceState> = resourceIds?.length
     ? { ...state[resourceType] }
     : {};
   const existingResourceIds = bootstrap
@@ -728,7 +733,7 @@ export async function pullResourceType(
         changedFiles.has(yamlPath)
       ) {
         console.log(`   ✏️  ${resourceId} (locally modified, preserving)`);
-        newStateSection[resourceId] = resource.id;
+        upsertState(newStateSection, resourceId, { uuid: resource.id });
         skipped++;
         continue;
       }
@@ -761,7 +766,7 @@ export async function pullResourceType(
           const stateMtime = statSync(stateFilePath).mtimeMs;
           if (localMtime > stateMtime) {
             console.log(`   ✏️  ${resourceId} (locally modified, preserving)`);
-            newStateSection[resourceId] = resource.id;
+            upsertState(newStateSection, resourceId, { uuid: resource.id });
             skipped++;
             continue;
           }
@@ -783,7 +788,7 @@ export async function pullResourceType(
         console.log(
           `   🗑️  ${resourceId} (deleted locally, intent in state — add to .vapi-ignore to stop tracking)`,
         );
-        newStateSection[resourceId] = resource.id;
+        upsertState(newStateSection, resourceId, { uuid: resource.id });
         skipped++;
         continue;
       }
@@ -825,8 +830,15 @@ export async function pullResourceType(
     if (isNew) created++;
     else updated++;
 
-    // Update state
-    newStateSection[resourceId] = resource.id;
+    // Update state with new content hash + timestamp (Stack F).
+    // Hashing the resolved-with-credentials payload (the form we will save
+    // to disk) keeps `lastPulledHash` aligned with the source-of-truth diff
+    // basis used by drift detection in Stack G.
+    upsertState(newStateSection, resourceId, {
+      uuid: resource.id,
+      lastPulledHash: hashPayload(withCredNames),
+      lastPulledAt: new Date().toISOString(),
+    });
   }
 
   // Update state with new mappings