@eduardbar/drift 1.2.0 → 1.4.0

package/src/saas/dashboard.ts

@@ -0,0 +1,172 @@
+import { resolve } from 'node:path'
+import type { SaasPolicyOverrides, SaasQueryOptions, SaasSnapshot, SaasSummary } from './types.js'
+import { DASHBOARD_BAR_MIN_WIDTH, DASHBOARD_BAR_UNIT, DASHBOARD_REPO_LIMIT } from './constants.js'
+import { assertPermissionInStore, defaultSaasStorePath, loadStoreInternal, saveStore } from './store.js'
+import {
+  DEFAULT_ORGANIZATION_ID,
+  computeRunsPerMonth,
+  computeUsersRegistered,
+  escapeHtml,
+  isRepoActive,
+  isWorkspaceActive,
+  matchesRepoScope,
+  matchesTenantScope,
+  matchesWorkspaceScope,
+} from './helpers.js'
+
+function assertSummaryReadPermission(store: ReturnType<typeof loadStoreInternal>, options?: SaasQueryOptions): void {
+  const shouldEnforceActorForScope = store.policy.strictActorEnforcement && Boolean(options?.organizationId || options?.workspaceId)
+  if (!options?.actorUserId && !shouldEnforceActorForScope) return
+
+  const organizationId = options?.organizationId ?? DEFAULT_ORGANIZATION_ID
+  assertPermissionInStore(store, {
+    operation: 'summary:read',
+    organizationId,
+    workspaceId: options?.workspaceId,
+    actorUserId: options?.actorUserId,
+  })
+}
+
+function buildWorkspaceStats(store: ReturnType<typeof loadStoreInternal>): Array<{
+  organizationId: string
+  id: string
+  runs: number
+  avgScore: number
+  lastRun: string
+}> {
+  return Object.values(store.workspaces)
+    .map((workspace) => {
+      const snapshots = store.snapshots.filter((snapshot) => snapshot.organizationId === workspace.organizationId && snapshot.workspaceId === workspace.id)
+      const runs = snapshots.length
+      const avgScore = runs === 0 ? 0 : Math.round(snapshots.reduce((sum, snapshot) => sum + snapshot.totalScore, 0) / runs)
+      const lastRun = snapshots.sort((a, b) => b.createdAt.localeCompare(a.createdAt))[0]?.createdAt ?? 'n/a'
+      return {
+        organizationId: workspace.organizationId,
+        id: workspace.id,
+        runs,
+        avgScore,
+        lastRun,
+      }
+    })
+    .sort((a, b) => b.avgScore - a.avgScore)
+}
+
+function buildRepoStats(store: ReturnType<typeof loadStoreInternal>): Array<{ workspaceId: string; name: string; runs: number; avgScore: number }> {
+  return Object.values(store.repos)
+    .map((repo) => {
+      const snapshots = store.snapshots.filter((snapshot) => snapshot.repoId === repo.id)
+      const runs = snapshots.length
+      const avgScore = runs === 0 ? 0 : Math.round(snapshots.reduce((sum, snapshot) => sum + snapshot.totalScore, 0) / runs)
+      return {
+        workspaceId: repo.workspaceId,
+        name: repo.name,
+        runs,
+        avgScore,
+      }
+    })
+    .sort((a, b) => b.avgScore - a.avgScore)
+    .slice(0, DASHBOARD_REPO_LIMIT)
+}
+
+function buildRunsRows(summary: SaasSummary): string {
+  return Object.entries(summary.runsPerMonth)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([month, count]) => {
+      const width = Math.max(DASHBOARD_BAR_MIN_WIDTH, count * DASHBOARD_BAR_UNIT)
+      return `<tr><td>${escapeHtml(month)}</td><td>${count}</td><td><div class="bar" style="width:${width}px"></div></td></tr>`
+    })
+    .join('')
+}
+
+function buildWorkspaceRows(workspaceStats: Array<{ organizationId: string; id: string; runs: number; avgScore: number; lastRun: string }>): string {
+  return workspaceStats
+    .map((workspace) => `<tr><td>${escapeHtml(workspace.organizationId)}</td><td>${escapeHtml(workspace.id)}</td><td>${workspace.runs}</td><td>${workspace.avgScore}</td><td>${escapeHtml(workspace.lastRun)}</td></tr>`)
+    .join('')
+}
+
+function buildRepoRows(repoStats: Array<{ workspaceId: string; name: string; runs: number; avgScore: number }>): string {
+  return repoStats
+    .map((repo) => `<tr><td>${escapeHtml(repo.workspaceId)}</td><td>${escapeHtml(repo.name)}</td><td>${repo.runs}</td><td>${repo.avgScore}</td></tr>`)
+    .join('')
+}
+
+function renderDashboardHtmlDocument(input: {
+  storeFile: string
+  summary: SaasSummary
+  runsRows: string
+  workspaceRows: string
+  repoRows: string
+}): string {
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><title>drift cloud dashboard</title><style>:root { color-scheme: light; } body { margin: 0; font-family: "Segoe UI", Arial, sans-serif; background: #f4f7fb; color: #0f172a; } main { max-width: 980px; margin: 0 auto; padding: 24px; } h1 { margin: 0 0 6px; } p.meta { margin: 0 0 20px; color: #475569; } .cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 12px; margin-bottom: 18px; } .card { background: #ffffff; border-radius: 10px; padding: 14px; border: 1px solid #dbe3ef; } .card .label { font-size: 12px; color: #64748b; text-transform: uppercase; letter-spacing: 0.08em; } .card .value { font-size: 26px; font-weight: 700; margin-top: 4px; } table { width: 100%; border-collapse: collapse; margin-top: 10px; background: #ffffff; border: 1px solid #dbe3ef; border-radius: 10px; overflow: hidden; } th, td { padding: 10px; border-bottom: 1px solid #e2e8f0; text-align: left; font-size: 14px; } th { background: #eef2f9; } .section { margin-top: 18px; } .bar { height: 10px; background: linear-gradient(90deg, #0ea5e9, #22c55e); border-radius: 999px; } .pill { display: inline-block; border-radius: 999px; padding: 4px 10px; font-size: 12px; font-weight: 600; } .pill.free { background: #dcfce7; color: #166534; } .pill.paid { background: #fee2e2; color: #991b1b; }</style></head><body><main><h1>drift cloud dashboard</h1><p class="meta">Store: ${escapeHtml(input.storeFile)}</p><div class="cards"><div class="card"><div class="label">Plan Phase</div><div class="value"><span class="pill ${input.summary.phase}">${input.summary.phase.toUpperCase()}</span></div></div><div class="card"><div class="label">Users</div><div class="value">${input.summary.usersRegistered}</div></div><div class="card"><div class="label">Active Workspaces</div><div class="value">${input.summary.workspacesActive}</div></div><div class="card"><div class="label">Active Repos</div><div class="value">${input.summary.reposActive}</div></div><div class="card"><div class="label">Snapshots</div><div class="value">${input.summary.totalSnapshots}</div></div><div class="card"><div class="label">Free Seats Left</div><div class="value">${input.summary.freeUsersRemaining}</div></div></div><section class="section"><h2>Runs Per Month</h2><table><thead><tr><th>Month</th><th>Runs</th><th>Trend</th></tr></thead><tbody>${input.runsRows || '<tr><td colspan="3">No runs yet</td></tr>'}</tbody></table></section><section class="section"><h2>Workspace Hotspots</h2><table><thead><tr><th>Organization</th><th>Workspace</th><th>Runs</th><th>Avg Score</th><th>Last Run</th></tr></thead><tbody>${input.workspaceRows || '<tr><td colspan="5">No workspace data</td></tr>'}</tbody></table></section><section class="section"><h2>Repo Hotspots</h2><table><thead><tr><th>Workspace</th><th>Repo</th><th>Runs</th><th>Avg Score</th></tr></thead><tbody>${input.repoRows || '<tr><td colspan="4">No repo data</td></tr>'}</tbody></table></section></main></body></html>`
+}
+
+export function listSaasSnapshots(options?: SaasQueryOptions): SaasSnapshot[] {
+  const storeFile = resolve(options?.storeFile ?? defaultSaasStorePath())
+  const store = loadStoreInternal(storeFile, options?.policy)
+
+  const shouldEnforceActorForScope = store.policy.strictActorEnforcement && Boolean(options?.organizationId || options?.workspaceId)
+  if (options?.actorUserId || shouldEnforceActorForScope) {
+    const organizationId = options?.organizationId ?? DEFAULT_ORGANIZATION_ID
+    assertPermissionInStore(store, {
+      operation: 'snapshot:read',
+      organizationId,
+      workspaceId: options?.workspaceId,
+      actorUserId: options?.actorUserId,
+    })
+  }
+
+  saveStore(storeFile, store)
+  return store.snapshots
+    .filter((snapshot) => matchesTenantScope(snapshot, options))
+    .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+}
+
+export function getSaasSummary(options?: SaasQueryOptions): SaasSummary {
+  const storeFile = resolve(options?.storeFile ?? defaultSaasStorePath())
+  const store = loadStoreInternal(storeFile, options?.policy)
+
+  assertSummaryReadPermission(store, options)
+  saveStore(storeFile, store)
+
+  const scopedSnapshots = store.snapshots.filter((snapshot) => matchesTenantScope(snapshot, options))
+  const scopedWorkspaces = Object.values(store.workspaces).filter((workspace) => matchesWorkspaceScope(workspace, options))
+  const scopedRepos = Object.values(store.repos).filter((repo) => matchesRepoScope(repo, options))
+
+  const usersRegistered = computeUsersRegistered(store, scopedSnapshots, options)
+  const workspacesActive = scopedWorkspaces.filter((workspace) => isWorkspaceActive(workspace)).length
+  const reposActive = scopedRepos.filter((repo) => isRepoActive(repo)).length
+  const runsPerMonth = computeRunsPerMonth(scopedSnapshots)
+  const thresholdReached = usersRegistered >= store.policy.freeUserThreshold
+
+  return {
+    policy: store.policy,
+    usersRegistered,
+    workspacesActive,
+    reposActive,
+    runsPerMonth,
+    totalSnapshots: scopedSnapshots.length,
+    phase: thresholdReached ? 'paid' : 'free',
+    thresholdReached,
+    freeUsersRemaining: Math.max(0, store.policy.freeUserThreshold - usersRegistered),
+  }
+}
+
+export function generateSaasDashboardHtml(options?: { storeFile?: string; policy?: SaasPolicyOverrides }): string {
+  const storeFile = resolve(options?.storeFile ?? defaultSaasStorePath())
+  const store = loadStoreInternal(storeFile, options?.policy)
+  const summary = getSaasSummary(options)
+
+  const workspaceStats = buildWorkspaceStats(store)
+  const repoStats = buildRepoStats(store)
+  const runsRows = buildRunsRows(summary)
+  const workspaceRows = buildWorkspaceRows(workspaceStats)
+  const repoRows = buildRepoRows(repoStats)
+
+  return renderDashboardHtmlDocument({
+    storeFile,
+    summary,
+    runsRows,
+    workspaceRows,
+    repoRows,
+  })
+}

package/src/saas/errors.ts

@@ -0,0 +1,45 @@
+import type { SaasOperation, SaasPermissionContext, SaasRole } from './types.js'
+
+export class SaasPermissionError extends Error {
+  readonly code = 'SAAS_PERMISSION_DENIED'
+  readonly operation: SaasOperation
+  readonly organizationId: string
+  readonly workspaceId?: string
+  readonly actorUserId?: string
+  readonly requiredRole: SaasRole
+  readonly actorRole?: SaasRole
+
+  constructor(context: SaasPermissionContext, requiredRole: SaasRole, actorRole?: SaasRole) {
+    const actor = context.actorUserId ?? 'unknown-actor'
+    const workspaceSuffix = context.workspaceId ? ` workspace='${context.workspaceId}'` : ''
+    const actualRole = actorRole ?? 'none'
+    super(
+      `Permission denied for operation '${context.operation}'. actor='${actor}' organization='${context.organizationId}'${workspaceSuffix} requiredRole='${requiredRole}' actualRole='${actualRole}'.`,
+    )
+    this.name = 'SaasPermissionError'
+    this.operation = context.operation
+    this.organizationId = context.organizationId
+    this.workspaceId = context.workspaceId
+    this.actorUserId = context.actorUserId
+    this.requiredRole = requiredRole
+    this.actorRole = actorRole
+  }
+}
+
+export class SaasActorRequiredError extends Error {
+  readonly code = 'SAAS_ACTOR_REQUIRED'
+  readonly operation: SaasOperation
+  readonly organizationId: string
+  readonly workspaceId?: string
+
+  constructor(context: SaasPermissionContext) {
+    const workspaceSuffix = context.workspaceId ? ` workspace='${context.workspaceId}'` : ''
+    super(
+      `Actor is required for operation '${context.operation}'. organization='${context.organizationId}'${workspaceSuffix}.`,
+    )
+    this.name = 'SaasActorRequiredError'
+    this.operation = context.operation
+    this.organizationId = context.organizationId
+    this.workspaceId = context.workspaceId
+  }
+}

package/src/saas/helpers.ts

@@ -0,0 +1,140 @@
+import type {
+  IngestOptions,
+  SaasPlan,
+  SaasPolicy,
+  SaasPolicyInput,
+  SaasPolicyOverrides,
+  SaasQueryOptions,
+  SaasRepo,
+  SaasRole,
+  SaasSnapshot,
+  SaasStore,
+  SaasWorkspace,
+  ScopedIdentity,
+} from './types.js'
+import {
+  ACTIVE_WINDOW_DAYS,
+  DEFAULT_ORGANIZATION_ID,
+  DEFAULT_SAAS_POLICY,
+  ROLE_PRIORITY,
+  VALID_PLANS,
+  VALID_ROLES,
+  daysAgo,
+} from './constants.js'
+
+export function resolveSaasPolicy(policy?: SaasPolicyInput): SaasPolicy {
+  const customPlanLimits = (policy && 'maxWorkspacesPerOrganizationByPlan' in policy)
+    ? (policy.maxWorkspacesPerOrganizationByPlan ?? {})
+    : {}
+
+  return {
+    ...DEFAULT_SAAS_POLICY,
+    ...(policy ?? {}),
+    maxWorkspacesPerOrganizationByPlan: {
+      ...DEFAULT_SAAS_POLICY.maxWorkspacesPerOrganizationByPlan,
+      ...customPlanLimits,
+    },
+  }
+}
+
+export function normalizePlan(plan?: string): SaasPlan {
+  if (!plan) return 'free'
+  return VALID_PLANS.includes(plan as SaasPlan) ? (plan as SaasPlan) : 'free'
+}
+
+export function normalizeRole(role?: string): SaasRole {
+  if (!role) return 'member'
+  return VALID_ROLES.includes(role as SaasRole) ? (role as SaasRole) : 'member'
+}
+
+export function hasRoleAtLeast(role: SaasRole | undefined, requiredRole: SaasRole): boolean {
+  if (!role) return false
+  return ROLE_PRIORITY[role] >= ROLE_PRIORITY[requiredRole]
+}
+
+export function workspaceKey(organizationId: string, workspaceId: string): string {
+  return `${organizationId}:${workspaceId}`
+}
+
+function repoKey(organizationId: string, workspaceId: string, repoName: string): string {
+  return `${workspaceKey(organizationId, workspaceId)}:${repoName}`
+}
+
+export function membershipKey(organizationId: string, workspaceId: string, userId: string): string {
+  return `${workspaceKey(organizationId, workspaceId)}:${userId}`
+}
+
+export function monthKey(isoDate: string): string {
+  const date = new Date(isoDate)
+  const month = String(date.getUTCMonth() + 1).padStart(2, '0')
+  return `${date.getUTCFullYear()}-${month}`
+}
+
+export function resolveScopedIdentity(options: IngestOptions): ScopedIdentity {
+  const organizationId = options.organizationId ?? DEFAULT_ORGANIZATION_ID
+  const workspaceId = options.workspaceId
+  const repoName = options.repoName ?? 'default'
+  return {
+    organizationId,
+    workspaceId,
+    workspaceKey: workspaceKey(organizationId, workspaceId),
+    repoName,
+    repoId: repoKey(organizationId, workspaceId, repoName),
+  }
+}
+
+export function isWorkspaceActive(workspace: SaasWorkspace): boolean {
+  return new Date(workspace.lastSeenAt).getTime() >= daysAgo(ACTIVE_WINDOW_DAYS)
+}
+
+export function isRepoActive(repo: SaasRepo): boolean {
+  return new Date(repo.lastSeenAt).getTime() >= daysAgo(ACTIVE_WINDOW_DAYS)
+}
+
+export function matchesTenantScope(snapshot: SaasSnapshot, options?: SaasQueryOptions): boolean {
+  if (!options?.organizationId && !options?.workspaceId) return true
+  if (options.organizationId && snapshot.organizationId !== options.organizationId) return false
+  if (options.workspaceId && snapshot.workspaceId !== options.workspaceId) return false
+  return true
+}
+
+export function matchesWorkspaceScope(workspace: SaasWorkspace, options?: SaasQueryOptions): boolean {
+  if (options?.organizationId && workspace.organizationId !== options.organizationId) return false
+  if (options?.workspaceId && workspace.id !== options.workspaceId) return false
+  return true
+}
+
+export function matchesRepoScope(repo: SaasRepo, options?: SaasQueryOptions): boolean {
+  if (options?.organizationId && repo.organizationId !== options.organizationId) return false
+  if (options?.workspaceId && repo.workspaceId !== options.workspaceId) return false
+  return true
+}
+
+export function computeRunsPerMonth(snapshots: SaasSnapshot[]): Record<string, number> {
+  const runsPerMonth: Record<string, number> = {}
+  for (const snapshot of snapshots) {
+    const key = monthKey(snapshot.createdAt)
+    runsPerMonth[key] = (runsPerMonth[key] ?? 0) + 1
+  }
+  return runsPerMonth
+}
+
+export function computeUsersRegistered(store: SaasStore, snapshots: SaasSnapshot[], options?: SaasQueryOptions): number {
+  if (!options?.organizationId && !options?.workspaceId) return Object.keys(store.users).length
+  return new Set(snapshots.map((snapshot) => snapshot.userId)).size
+}
+
+export function escapeHtml(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;')
+}
+
+export function mergePolicy(policy: SaasPolicyOverrides | undefined, base: SaasStore['policy']): SaasPolicy {
+  return resolveSaasPolicy({ ...base, ...(policy ?? {}) })
+}
+
+export { DEFAULT_ORGANIZATION_ID }

package/src/saas/ingest.ts

@@ -0,0 +1,278 @@
+import { resolve } from 'node:path'
+import type { DriftReportInput, IngestMutationContext, IngestOptions, SaasPlan, SaasRole, SaasSnapshot, SaasStore } from './types.js'
+import { createRandomId } from './constants.js'
+import { SaasActorRequiredError } from './errors.js'
+import { applyRetentionPolicy, assertPermissionInStore, defaultSaasStorePath, loadStoreInternal, saveStore } from './store.js'
+import { membershipKey, monthKey, normalizePlan, normalizeRole, resolveScopedIdentity } from './helpers.js'
+import { appendPlanChange } from './plan-change.js'
+
+function assertWorkspaceLimit(store: SaasStore, scoped: IngestMutationContext['scoped'], effectivePlan: SaasPlan): void {
+  const organization = store.organizations[scoped.organizationId]
+  const workspaceLimit = store.policy.maxWorkspacesPerOrganizationByPlan[effectivePlan]
+  const workspaceExists = Boolean(store.workspaces[scoped.workspaceKey])
+  const workspaceCount = organization?.workspaceIds.length ?? 0
+
+  if (!workspaceExists && workspaceCount >= workspaceLimit) {
+    throw new Error(`Organization '${scoped.organizationId}' on plan '${effectivePlan}' reached max workspaces (${workspaceLimit}).`)
+  }
+}
+
+function assertFreeThresholdLimit(store: SaasStore, userId: string): void {
+  const usersRegistered = Object.keys(store.users).length
+  const isFreePhase = usersRegistered < store.policy.freeUserThreshold
+  if (!isFreePhase) return
+  if (!store.users[userId] && usersRegistered + 1 > store.policy.freeUserThreshold) {
+    throw new Error(`Free threshold reached (${store.policy.freeUserThreshold} users).`)
+  }
+}
+
+function assertRepoLimit(store: SaasStore, scoped: IngestMutationContext['scoped']): void {
+  const workspace = store.workspaces[scoped.workspaceKey]
+  const repoExists = Boolean(store.repos[scoped.repoId])
+  const repoCount = workspace?.repoIds.length ?? 0
+  if (!repoExists && repoCount >= store.policy.maxReposPerWorkspace) {
+    throw new Error(`Workspace '${scoped.workspaceId}' reached max repos (${store.policy.maxReposPerWorkspace}).`)
+  }
+}
+
+function countWorkspaceRunsThisMonth(store: SaasStore, scoped: IngestMutationContext['scoped'], currentMonth: string): number {
+  return store.snapshots.filter((snapshot) => {
+    return snapshot.organizationId === scoped.organizationId
+      && snapshot.workspaceId === scoped.workspaceId
+      && monthKey(snapshot.createdAt) === currentMonth
+  }).length
+}
+
+function assertGuardrails(store: SaasStore, options: IngestOptions, nowIso: string): void {
+  const scoped = resolveScopedIdentity(options)
+  const organization = store.organizations[scoped.organizationId]
+  const effectivePlan = normalizePlan(options.plan ?? organization?.plan)
+  assertWorkspaceLimit(store, scoped, effectivePlan)
+  assertFreeThresholdLimit(store, options.userId)
+  assertRepoLimit(store, scoped)
+
+  const currentMonth = monthKey(nowIso)
+  const runsThisMonth = countWorkspaceRunsThisMonth(store, scoped, currentMonth)
+  if (runsThisMonth >= store.policy.maxRunsPerWorkspacePerMonth) {
+    throw new Error(`Workspace '${scoped.workspaceId}' reached max monthly runs (${store.policy.maxRunsPerWorkspacePerMonth}).`)
+  }
+}
+
+function upsertUser(store: SaasStore, userId: string, nowIso: string): void {
+  const user = store.users[userId]
+  if (user) {
+    user.lastSeenAt = nowIso
+    return
+  }
+
+  store.users[userId] = {
+    id: userId,
+    createdAt: nowIso,
+    lastSeenAt: nowIso,
+  }
+}
+
+function maybeUpdateOrganizationPlanFromIngest(context: IngestMutationContext): void {
+  const { store, scoped, requestedPlan, options, nowIso } = context
+  const existingOrg = store.organizations[scoped.organizationId]
+  if (!existingOrg || !options.plan || existingOrg.plan === requestedPlan) return
+
+  if (options.actorUserId) {
+    assertPermissionInStore(store, {
+      operation: 'billing:write',
+      organizationId: scoped.organizationId,
+      actorUserId: options.actorUserId,
+    })
+  }
+
+  const previousPlan = existingOrg.plan
+  existingOrg.plan = requestedPlan
+  appendPlanChange(store, {
+    organizationId: scoped.organizationId,
+    fromPlan: previousPlan,
+    toPlan: requestedPlan,
+    changedAt: nowIso,
+    changedByUserId: options.actorUserId ?? options.userId,
+    reason: 'ingest-option-plan-change',
+  })
+}
+
+function ensureOrganizationForIngest(context: IngestMutationContext): void {
+  const { store, scoped, requestedPlan, nowIso } = context
+  const existingOrg = store.organizations[scoped.organizationId]
+  if (existingOrg) {
+    existingOrg.lastSeenAt = nowIso
+    maybeUpdateOrganizationPlanFromIngest(context)
+    return
+  }
+
+  store.organizations[scoped.organizationId] = {
+    id: scoped.organizationId,
+    plan: requestedPlan,
+    createdAt: nowIso,
+    lastSeenAt: nowIso,
+    workspaceIds: [],
+  }
+}
+
+function upsertWorkspaceForIngest(
+  store: SaasStore,
+  scoped: IngestMutationContext['scoped'],
+  userId: string,
+  nowIso: string,
+): { wasCreated: boolean } {
+  const workspace = store.workspaces[scoped.workspaceKey]
+  if (workspace) {
+    workspace.lastSeenAt = nowIso
+    if (!workspace.userIds.includes(userId)) workspace.userIds.push(userId)
+    return { wasCreated: false }
+  }
+
+  store.workspaces[scoped.workspaceKey] = {
+    id: scoped.workspaceId,
+    organizationId: scoped.organizationId,
+    createdAt: nowIso,
+    lastSeenAt: nowIso,
+    userIds: [userId],
+    repoIds: [],
+  }
+
+  const org = store.organizations[scoped.organizationId]
+  if (!org.workspaceIds.includes(scoped.workspaceId)) org.workspaceIds.push(scoped.workspaceId)
+  return { wasCreated: true }
+}
+
+function upsertMembershipForIngest(context: IngestMutationContext, workspaceWasCreated: boolean): SaasRole {
+  const { store, scoped, options, nowIso } = context
+  const membershipId = membershipKey(scoped.organizationId, scoped.workspaceId, options.userId)
+  const membership = store.memberships[membershipId]
+  let role = normalizeRole(options.role)
+  if (!membership && workspaceWasCreated) role = 'owner'
+
+  if (membership) {
+    membership.lastSeenAt = nowIso
+    if (options.role) membership.role = normalizeRole(options.role)
+    return membership.role
+  }
+
+  store.memberships[membershipId] = {
+    id: membershipId,
+    organizationId: scoped.organizationId,
+    workspaceId: scoped.workspaceId,
+    userId: options.userId,
+    role,
+    createdAt: nowIso,
+    lastSeenAt: nowIso,
+  }
+  return role
+}
+
+function upsertRepoForIngest(store: SaasStore, scoped: IngestMutationContext['scoped'], nowIso: string): void {
+  const repo = store.repos[scoped.repoId]
+  if (repo) {
+    repo.lastSeenAt = nowIso
+    return
+  }
+
+  store.repos[scoped.repoId] = {
+    id: scoped.repoId,
+    organizationId: scoped.organizationId,
+    workspaceId: scoped.workspaceId,
+    name: scoped.repoName,
+    createdAt: nowIso,
+    lastSeenAt: nowIso,
+  }
+
+  const workspace = store.workspaces[scoped.workspaceKey]
+  if (!workspace.repoIds.includes(scoped.repoId)) workspace.repoIds.push(scoped.repoId)
+}
+
+function createSnapshotFromReport(report: DriftReportInput, context: IngestMutationContext, role: SaasRole): SaasSnapshot {
+  const { store, scoped, options, nowIso, requestedPlan } = context
+  return {
+    id: createRandomId(String(Date.now())),
+    createdAt: nowIso,
+    scannedAt: report.scannedAt,
+    organizationId: scoped.organizationId,
+    workspaceId: scoped.workspaceId,
+    userId: options.userId,
+    role,
+    plan: normalizePlan(store.organizations[scoped.organizationId]?.plan ?? requestedPlan),
+    repoId: scoped.repoId,
+    repoName: scoped.repoName,
+    targetPath: report.targetPath,
+    totalScore: report.totalScore,
+    totalIssues: report.totalIssues,
+    totalFiles: report.totalFiles,
+    summary: {
+      errors: report.summary.errors,
+      warnings: report.summary.warnings,
+      infos: report.summary.infos,
+    },
+  }
+}
+
+function assertIngestActorRequirement(options: IngestOptions, scoped: IngestMutationContext['scoped'], store: SaasStore): void {
+  if (!store.policy.strictActorEnforcement || options.actorUserId) return
+  throw new SaasActorRequiredError({
+    operation: 'snapshot:write',
+    organizationId: scoped.organizationId,
+    workspaceId: scoped.workspaceId,
+  })
+}
+
+function assertIngestPermissionForActor(store: SaasStore, scoped: IngestMutationContext['scoped'], actorUserId?: string): void {
+  if (!actorUserId) return
+
+  const workspaceExists = Boolean(store.workspaces[scoped.workspaceKey])
+  const organizationExists = Boolean(store.organizations[scoped.organizationId])
+  if (workspaceExists) {
+    assertPermissionInStore(store, {
+      operation: 'snapshot:write',
+      organizationId: scoped.organizationId,
+      workspaceId: scoped.workspaceId,
+      actorUserId,
+    })
+    return
+  }
+
+  if (organizationExists) {
+    assertPermissionInStore(store, {
+      operation: 'billing:write',
+      organizationId: scoped.organizationId,
+      actorUserId,
+    })
+  }
+}
+
+export function ingestSnapshotFromReport(report: DriftReportInput, options: IngestOptions): SaasSnapshot {
+  const storeFile = resolve(options.storeFile ?? defaultSaasStorePath())
+  const store = loadStoreInternal(storeFile, options.policy)
+  const nowIso = new Date().toISOString()
+  const scoped = resolveScopedIdentity(options)
+  const requestedPlan = normalizePlan(options.plan)
+  const context: IngestMutationContext = {
+    store,
+    scoped,
+    options,
+    nowIso,
+    requestedPlan,
+  }
+
+  assertIngestActorRequirement(options, scoped, store)
+  assertIngestPermissionForActor(store, scoped, options.actorUserId)
+  assertGuardrails(store, options, nowIso)
+
+  upsertUser(store, options.userId, nowIso)
+  ensureOrganizationForIngest(context)
+  const workspaceState = upsertWorkspaceForIngest(store, scoped, options.userId, nowIso)
+  const role = upsertMembershipForIngest(context, workspaceState.wasCreated)
+  upsertRepoForIngest(store, scoped, nowIso)
+
+  const snapshot = createSnapshotFromReport(report, context, role)
+  store.snapshots.push(snapshot)
+  applyRetentionPolicy(store)
+  saveStore(storeFile, store)
+
+  return snapshot
+}