┌─────────────────────────────────────────────────────────────┐
│ 1. Hook creates session                                     │
│    createSDKSession(contentSessionId, project, prompt)      │
│                                                              │
│    Database state:                                          │
│    ├─ content_session_id: "user-session-123"               │
│    └─ memory_session_id: NULL (not yet captured)           │
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. SDKAgent starts, checks hasRealMemorySessionId           │
│    const hasReal = !!memorySessionId                        │
│    → FALSE (it's NULL)                                      │
│    → Resume NOT used (fresh SDK session)                    │
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. First SDK message arrives with session_id                │
│    ensureMemorySessionIdRegistered(sessionDbId, "sdk-gen-abc123") │
│                                                              │
│    Database state:                                          │
│    ├─ content_session_id: "user-session-123"               │
│    └─ memory_session_id: "sdk-gen-abc123" (real!)          │
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│ 4. Subsequent prompts may use resume                        │
│    const shouldResume =                                      │
│      !!memorySessionId && lastPromptNumber > 1 && !forceInit│
│    → TRUE only for continuation prompts in the same runtime │
│    → Resume parameter: { resume: "sdk-gen-abc123" }         │
└─────────────────────────────────────────────────────────────┘

// SessionStore.ts
storeObservation(memorySessionId, project, observation, ...);

const hasRealMemorySessionId = !!session.memorySessionId;

// ❌ FORBIDDEN - Would resume user's session instead of memory session!
query({ resume: contentSessionId })

// ✅ CORRECT - Only resume for a continuation prompt in a valid runtime
query({
  ...(
    !!memorySessionId &&
    lastPromptNumber > 1 &&
    !forceInit &&
    { resume: memorySessionId }
  )
})

# Run all session ID tests
bun test tests/session_id_usage_validation.test.ts

# Run all tests
bun test

# Run with verbose output
bun test --verbose

// WRONG - Don't store observations before memorySessionId is available
storeObservation(session.contentSessionId, ...)

// WRONG - memorySessionId alone is not enough
if (session.memorySessionId) {
  query({ resume: session.memorySessionId })
}

// WRONG - Can be NULL before SDK session is captured
const resumeId = session.memorySessionId

// Only store after a real memorySessionId has been captured or synthesized
storeObservation(session.memorySessionId, project, obs, ...)

const hasRealMemorySessionId = !!session.memorySessionId;

query({
  prompt: messageGenerator,
  options: {
    ...(
      hasRealMemorySessionId &&
      session.lastPromptNumber > 1 &&
      !session.forceInit &&
      { resume: session.memorySessionId }
    ),
    // ... other options
  }
})

-- See both session IDs
SELECT
  id,
  content_session_id,
  memory_session_id,
  CASE
    WHEN memory_session_id IS NULL THEN 'NOT_CAPTURED'
    ELSE 'CAPTURED'
  END as state
FROM sdk_sessions
WHERE content_session_id = 'your-session-id';

-- Should return 0 rows if FK integrity is maintained
SELECT o.*
FROM observations o
LEFT JOIN sdk_sessions s ON o.memory_session_id = s.memory_session_id
WHERE s.id IS NULL;

-- See which observations belong to a session
SELECT
  o.id,
  o.title,
  o.memory_session_id,
  s.content_session_id,
  s.memory_session_id as session_memory_id
FROM observations o
JOIN sdk_sessions s ON o.memory_session_id = s.memory_session_id
WHERE s.content_session_id = 'your-session-id';