@alteran/astro 0.3.9 → 0.6.1

package/src/db/account.ts

@@ -26,7 +26,8 @@ export async function getAccountByIdentifier(env: Env, identifier: string): Prom
   if (ident.handle) clauses.push(eq(account.handle, ident.handle));
   if (clauses.length === 0) return null;
   const where = clauses.length === 1 ? clauses[0] : or(...clauses);
-  return db.select().from(account).where(where).get();
+  const row = await db.select().from(account).where(where).get();
+  return row ?? null;
 }
 
 export async function createAccount(env: Env, data: {
@@ -105,7 +106,12 @@ export async function markRefreshTokenRotated(env: Env, id: string, nextId: stri
 
 export async function getRefreshToken(env: Env, id: string): Promise<RefreshTokenRow | null> {
   const db = getDb(env);
-  return db.select().from(refresh_token_store).where(eq(refresh_token_store.id, id)).get();
+  const row = await db
+    .select()
+    .from(refresh_token_store)
+    .where(eq(refresh_token_store.id, id))
+    .get();
+  return row ?? null;
 }
 
 export async function deleteRefreshToken(env: Env, id: string): Promise<void> {
@@ -115,8 +121,8 @@ export async function deleteRefreshToken(env: Env, id: string): Promise<void> {
 
 export async function cleanupExpiredRefreshTokens(env: Env, now: number): Promise<number> {
   const db = getDb(env);
-  const res = await db.delete(refresh_token_store).where(lt(refresh_token_store.expiresAt, now)).run();
-  return res.meta.changes ?? 0;
+  const response = await db.delete(refresh_token_store).where(lt(refresh_token_store.expiresAt, now)).run();
+  return response.meta.changes ?? 0;
 }
 
 export async function getSecret(env: Env, key: string): Promise<string | null> {
@@ -137,9 +143,22 @@ export async function setSecret(env: Env, key: string, value: string): Promise<v
 }
 
 export async function getOrCreateSecret(env: Env, key: string, factory: () => Promise<string>): Promise<string> {
+  // Check if secret already exists
   const existing = await getSecret(env, key);
   if (existing) return existing;
+
+  // Generate a new value
   const value = await factory();
-  await setSecret(env, key, value);
-  return value;
+
+  // Use onConflictDoNothing to avoid race conditions where multiple Workers
+  // might try to create the secret simultaneously. The first one wins.
+  const db = getDb(env);
+  await db
+    .insert(secret)
+    .values({ key, value, updatedAt: NOW() })
+    .onConflictDoNothing();
+
+  // Re-read to get the actual stored value (might be from another Worker)
+  const stored = await getSecret(env, key);
+  return stored ?? value;
 }

package/src/db/client.ts

@@ -3,5 +3,5 @@ import { drizzle } from 'drizzle-orm/d1';
 import type { Env } from '../env';
 
 export function getDb(env: Env) {
-  return drizzle(env.DB);
+  return drizzle(env.ALTERAN_DB);
 }

package/src/db/dal.ts

@@ -2,10 +2,15 @@ import { getDb } from './client';
 import { record, type NewRecordRow, blob_ref, blob_usage, blob_quota } from './schema';
 import type { Env } from '../env';
 import { eq, inArray, and, sql } from 'drizzle-orm';
+import { type AccountState, toRow, fromRow } from '../lib/account-state';
 
 export async function putRecord(env: Env, row: NewRecordRow) {
   const db = getDb(env);
-  await db.insert(record).values(row).onConflictDoUpdate({
+  const toInsert: NewRecordRow = {
+    ...row,
+    createdAt: row.createdAt ?? Date.now(),
+  };
+  await db.insert(record).values(toInsert).onConflictDoUpdate({
     target: record.uri,
     set: {
       cid: sql.raw(`excluded.${record.cid.name}`),
@@ -16,8 +21,8 @@ export async function putRecord(env: Env, row: NewRecordRow) {
 
 export async function getRecord(env: Env, uri: string) {
   const db = getDb(env);
-  const res = await db.select().from(record).where(eq(record.uri, uri)).get();
-  return res ?? null;
+  const result = await db.select().from(record).where(eq(record.uri, uri)).get();
+  return result ?? null;
 }
 
 export async function deleteRecord(env: Env, uri: string) {
@@ -109,40 +114,46 @@ export async function updateBlobQuota(env: Env, did: string, bytesAdded: number,
 
 export async function checkBlobQuota(env: Env, did: string, additionalBytes: number): Promise<boolean> {
   const quota = await getBlobQuota(env, did);
-  const maxBytes = parseInt((env as any).PDS_BLOB_QUOTA_BYTES || '10737418240', 10); // Default: 10GB
+  const maxBytes = parseInt(env.PDS_BLOB_QUOTA_BYTES || '10737418240', 10);
 
   return (quota.total_bytes + additionalBytes) <= maxBytes;
 }
 
-// Account state management for migration support
-export async function getAccountState(env: Env, did: string) {
+// Account state management for migration support. Reads/writes route through
+// the AccountState FSM so the persisted row stays consistent with whatever the
+// firehose broadcast emits.
+export async function getAccountState(env: Env, did: string): Promise<AccountState | null> {
   const db = getDb(env);
   const { account_state } = await import('./schema');
-  const state = await db.select().from(account_state).where(eq(account_state.did, did)).get();
-  return state ?? null;
+  const row = await db.select().from(account_state).where(eq(account_state.did, did)).get();
+  return row ? fromRow(row) : null;
 }
 
-export async function createAccountState(env: Env, did: string, active: boolean = false) {
+export async function setAccountState(env: Env, did: string, state: AccountState): Promise<void> {
   const db = getDb(env);
   const { account_state } = await import('./schema');
-  await db.insert(account_state).values({
-    did,
-    active,
-    created_at: Date.now(),
-  }).run();
+  const row = toRow(state);
+  await db
+    .insert(account_state)
+    .values({ did, ...row, created_at: Date.now() })
+    .onConflictDoUpdate({
+      target: account_state.did,
+      set: row,
+    })
+    .run();
 }
 
-export async function setAccountActive(env: Env, did: string, active: boolean) {
-  const db = getDb(env);
-  const { account_state } = await import('./schema');
-  await db.update(account_state)
-    .set({ active })
-    .where(eq(account_state.did, did))
-    .run();
+export async function createAccountState(env: Env, did: string, active: boolean = false): Promise<void> {
+  await setAccountState(env, did, active ? { tag: 'active' } : { tag: 'deactivated' });
+}
+
+export async function setAccountActive(env: Env, did: string, active: boolean): Promise<void> {
+  await setAccountState(env, did, active ? { tag: 'active' } : { tag: 'deactivated' });
 }
 
 export async function isAccountActive(env: Env, did: string): Promise<boolean> {
   const state = await getAccountState(env, did);
-  // If no account state exists, assume active (backward compatibility)
-  return state?.active ?? true;
+  // If no account state row exists, assume active (backward compatibility
+  // with rows that predate the migration).
+  return state === null ? true : state.tag === 'active';
 }

package/src/db/repo.ts

@@ -7,9 +7,10 @@ import { createCommit, signCommit, commitCid, generateTid, serializeCommit } fro
 import { CID } from 'multiformats/cid';
 import { resolveSecret } from '../lib/secrets';
 import { encodeBlocksForCommit } from '../services/car';
+import { ServerMisconfigured } from '../lib/errors';
 
 export async function getRoot(env: Env) {
-  const db = drizzle(env.DB);
+  const db = drizzle(env.ALTERAN_DB);
   const did = (await resolveSecret(env.PDS_DID)) ?? 'did:example:single-user';
   return db.select().from(repo_root).where(eq(repo_root.did, did)).get();
 }
@@ -17,7 +18,10 @@ export async function getRoot(env: Env) {
 /**
  * Bump the repository root to a new revision with signed commit
  */
-export async function bumpRoot(env: Env, prevMstRoot?: CID): Promise<{
+export async function bumpRoot(env: Env, prevMstRoot?: CID, currentMstRoot?: CID, opts?: {
+  ops?: import('../lib/firehose/frames').RepoOp[];
+  newMstBlocks?: Array<[CID, Uint8Array]>;
+}): Promise<{
   commitCid: string;
   rev: string;
   ops: import('../lib/firehose/frames').RepoOp[];
@@ -26,40 +30,39 @@ export async function bumpRoot(env: Env, prevMstRoot?: CID): Promise<{
   sig: string;
   blocks: string; // base64-encoded CAR
 }> {
-  const db = drizzle(env.DB);
+  const db = drizzle(env.ALTERAN_DB);
   const did = (await resolveSecret(env.PDS_DID)) ?? 'did:example:single-user';
 
-  // Resolve signing key (use ephemeral dev key if not configured and not production)
+  // Falls back to an ephemeral key only in non-production so dev runs work
+  // without REPO_SIGNING_KEY; prod always requires the configured key.
   const signingKey = await getSigningKey(env);
 
-  // Get current repo state
   const row = await db.select().from(repo_root).where(eq(repo_root.did, did)).get();
   const prevCommitCid = row?.commitCid ? CID.parse(row.commitCid) : null;
 
-  // Get the current MST root
+  // Prefer caller-provided pointer to avoid an extra MST load on the
+  // batched-write path that already knows the new root.
   const repoManager = new RepoManager(env);
-  const mst = await repoManager.getOrCreateRoot();
-  const mstRootCid = await mst.getPointer();
+  const mstRootCid = currentMstRoot
+    ? currentMstRoot
+    : await (async () => {
+        const mst = await repoManager.getOrCreateRoot();
+        return mst.getPointer();
+      })();
+
+  // Caller-provided ops avoid the more expensive full-tree diff.
+  const ops = opts?.ops !== undefined
+    ? opts.ops
+    : (prevMstRoot ? await repoManager.extractOps(prevMstRoot, mstRootCid) : []);
 
-  // Extract operations if we have a previous MST root
-  const ops = prevMstRoot
-    ? await repoManager.extractOps(prevMstRoot, mstRootCid)
-    : [];
-
-  // Generate new revision (TID)
   const rev = generateTid();
-
-  // Create commit
   const commit = createCommit(did, mstRootCid, rev, prevCommitCid);
-
-  // Sign commit
   const signedCommit = await signCommit(commit, signingKey);
-
-  // Calculate commit CID
   const cid = await commitCid(signedCommit);
   const cidString = cid.toString();
 
-  // Update repo root - use sql.raw with excluded to properly reference INSERT values
+  // sql.raw('excluded.X') references the just-inserted VALUES so the upsert
+  // updates with the new value rather than a stale parameter.
   await db
     .insert(repo_root)
     .values({
@@ -94,7 +97,7 @@ export async function bumpRoot(env: Env, prevMstRoot?: CID): Promise<{
   await appendCommit(env, cidString, rev, commitData, sigBase64);
 
   // Encode blocks as CAR for firehose
-  const blocksBytes = await encodeBlocksForCommit(env, cid, mstRootCid, ops);
+  const blocksBytes = await encodeBlocksForCommit(env, cid, mstRootCid, ops, opts?.newMstBlocks);
   // Encode to base64 (workers-safe)
   let blocksBase64 = '';
   for (const b of blocksBytes) blocksBase64 += String.fromCharCode(b);
@@ -104,7 +107,7 @@ export async function bumpRoot(env: Env, prevMstRoot?: CID): Promise<{
 }
 
 export async function appendCommit(env: Env, cid: string, rev: string, data: string, sig: string) {
-  const db = drizzle(env.DB);
+  const db = drizzle(env.ALTERAN_DB);
   const ts = Date.now();
 
   await db
@@ -119,29 +122,26 @@ export async function appendCommit(env: Env, cid: string, rev: string, data: str
     .run();
 }
 
-// Cache for dev-mode ephemeral signing key (in-memory for worker/astro dev)
+// Cache for dev-mode ephemeral signing key (hex string)
 let cachedDevSigningKey: string | undefined;
 
 async function getSigningKey(env: Env): Promise<string> {
-  const configured = await resolveSecret(env.REPO_SIGNING_KEY);
-  if (configured && configured.trim() !== '') return configured;
+  const configured = await resolveSecret((env as any).REPO_SIGNING_KEY);
+  if (configured && configured.trim() !== '') return configured.trim();
 
   const envName = (env as any).ENVIRONMENT || 'development';
   if (envName !== 'production') {
     if (cachedDevSigningKey) return cachedDevSigningKey;
-    // Generate an ephemeral Ed25519 keypair and cache private key (PKCS#8 base64)
-    const keyPair = await crypto.subtle.generateKey(
-      { name: 'Ed25519', namedCurve: 'Ed25519' } as any,
-      true,
-      ['sign', 'verify']
-    );
-    const pkcs8 = await crypto.subtle.exportKey('pkcs8', keyPair.privateKey);
-    let s = '';
-    const u8 = new Uint8Array(pkcs8);
-    for (let i = 0; i < u8.length; i++) s += String.fromCharCode(u8[i]);
-    cachedDevSigningKey = btoa(s);
+    // Generate an ephemeral secp256k1 keypair and cache private key (hex)
+    const { Secp256k1Keypair } = await import('@atproto/crypto');
+    const kp = await Secp256k1Keypair.create({ exportable: true });
+    const privBytes = await kp.export();
+    // to hex
+    let hex = '';
+    for (const b of privBytes) hex += b.toString(16).padStart(2, '0');
+    cachedDevSigningKey = hex;
     return cachedDevSigningKey;
   }
 
-  throw new Error('REPO_SIGNING_KEY not configured');
+  throw new ServerMisconfigured('REPO_SIGNING_KEY not configured');
 }

package/src/db/schema.ts

@@ -103,10 +103,14 @@ export const blob_quota = sqliteTable('blob_quota', {
   updated_at: integer('updated_at').notNull(),
 });
 
-// Account state for migration support (single-user PDS)
+// Account state for migration support (single-user PDS). The active flag
+// stays for legacy reads, but the full FSM is recovered from
+// (active, status, suspended_until) via fromRow in src/lib/account-state.ts.
 export const account_state = sqliteTable('account_state', {
   did: text('did').primaryKey().notNull(),
   active: integer('active', { mode: 'boolean' }).notNull().default(false),
+  status: text('status'),
+  suspended_until: integer('suspended_until'),
   created_at: integer('created_at').notNull(),
 });
 

package/src/db/seed.ts

@@ -1,14 +1,6 @@
-import { drizzle } from 'drizzle-orm/d1';
-import { repo_root } from './schema';
-
-export async function seed(db: D1Database, did: string) {
-  const d1 = drizzle(db);
-  const rows = await d1.select().from(repo_root).all();
-  if (rows.length === 0) {
-    await d1.insert(repo_root).values({
-      did,
-      commitCid: 'bafyreih2y3p6t2i4y567q2z5q2z5q2z5q2z5q2z5q2z5q2z5q2z5q2z5q',
-      rev: 0,
-    });
-  }
+export async function seed(_db: D1Database, _did: string) {
+  // Intentional no-op. The repo_root row is created via UPSERT by bumpRoot()
+  // on the first write. Previously this function seeded a placeholder commit
+  // CID that wasn't a valid CIDv1, causing the first applyWrites to throw
+  // `SyntaxError: Unexpected end of data` when CID.parse decoded it.
 }

package/src/entrypoints/server.ts

@@ -1,29 +1,9 @@
 import type { SSRManifest } from 'astro';
-import { App } from 'astro/app';
-import { handle } from '@astrojs/cloudflare/handler';
+import { createPdsFetchHandler } from '../worker/runtime';
 import { Sequencer } from '../worker/sequencer';
 
 export function createExports(manifest: SSRManifest) {
-  const app = new App(manifest);
-  const fetch = async (request: Request, env: unknown, context: unknown) => {
-    // Ensure ASSETS binding exists to satisfy @astrojs/cloudflare handler
-    // even when the worker has no static asset binding configured.
-    const e = env as any;
-    if (!e?.ASSETS || typeof e.ASSETS.fetch !== 'function') {
-      e.ASSETS = {
-        async fetch() {
-          return new Response('Not Found', {
-            status: 404,
-            headers: { 'Cache-Control': 'public, max-age=60' },
-          });
-        },
-      };
-    }
-
-    // Delegate to the Cloudflare adapter handler while preserving Alteran additions.
-    return await handle(manifest, app, request, e, context as any);
-  };
-
+  const fetch = createPdsFetchHandler({ manifest });
   return {
     default: { fetch },
     Sequencer,

package/src/handlers/debug.ts

@@ -3,7 +3,7 @@ import { putRecord as dalPutRecord, getRecord as dalGetRecord } from '../db/dal'
 
 export async function POST_db_bootstrap(ctx: APIContext) {
   const env: any = (ctx.locals as any).runtime?.env ?? (ctx.locals as any) ?? (globalThis as any);
-  const db = env.DB;
+  const db = env.ALTERAN_DB;
   await db.exec("CREATE TABLE IF NOT EXISTS record (uri TEXT PRIMARY KEY, cid TEXT NOT NULL, json TEXT NOT NULL, created_at INTEGER DEFAULT (strftime('%s','now')));");
   await db.exec("CREATE TABLE IF NOT EXISTS blob (cid TEXT PRIMARY KEY, key TEXT NOT NULL, mime TEXT NOT NULL, size INTEGER NOT NULL);");
   await db.exec("CREATE TABLE IF NOT EXISTS blob_usage (record_uri TEXT NOT NULL, key TEXT NOT NULL);");

package/src/handlers/ready.ts

@@ -2,7 +2,7 @@ import type { APIContext } from 'astro';
 
 export async function GET(ctx: APIContext) {
   try {
-    const db = (ctx.locals as any).runtime?.env?.DB ?? (ctx.locals as any).DB ?? (globalThis as any).DB;
+    const db = (ctx.locals as any).runtime?.env?.ALTERAN_DB ?? (ctx.locals as any).ALTERAN_DB ?? (globalThis as any).ALTERAN_DB;
     if (db) {
       await db.prepare('select 1').first();
     }

package/src/handlers/root.ts

@@ -1,8 +1,8 @@
 import type { APIContext } from 'astro';
 
 const HTML_TEMPLATE = (
-  handle,
-  did,
+  handle: string,
+  did: string,
 ) => `<!DOCTYPE html>
 <html lang="en">
   <head>
@@ -96,8 +96,8 @@ const HTML_TEMPLATE = (
 
 export async function GET({ locals }: APIContext) {
   const { env } = locals.runtime ?? {};
-  const handle = env?.PDS_HANDLE ?? 'unknown.handle';
-  const did = env?.PDS_DID ?? 'did:plc:unknown';
+  const handle = String(env?.PDS_HANDLE ?? 'unknown.handle');
+  const did = String(env?.PDS_DID ?? 'did:plc:unknown');
 
   return new Response(HTML_TEMPLATE(handle, did), {
     status: 200,

package/src/handlers/xrpc.server.refreshSession.ts

@@ -23,9 +23,9 @@ export async function POST(ctx: APIContext) {
   if (!ver || ver.payload.t !== 'refresh') return Response.json({ error: 'InvalidToken' }, { status: 401 });
 
   const jtiOld = String(ver.payload.jti || '');
-  if (jtiOld && env.DB) {
-    await env.DB.exec('CREATE TABLE IF NOT EXISTS token_revocation (refresh_jti TEXT PRIMARY KEY, exp INTEGER NOT NULL);');
-    const row: any = await env.DB.prepare('SELECT refresh_jti FROM token_revocation WHERE refresh_jti=?').bind(jtiOld).first();
+  if (jtiOld && env.ALTERAN_DB) {
+    await env.ALTERAN_DB.exec('CREATE TABLE IF NOT EXISTS token_revocation (refresh_jti TEXT PRIMARY KEY, exp INTEGER NOT NULL);');
+    const row: any = await env.ALTERAN_DB.prepare('SELECT refresh_jti FROM token_revocation WHERE refresh_jti=?').bind(jtiOld).first();
     if (row?.refresh_jti) return Response.json({ error: 'InvalidToken' }, { status: 401 });
   }
 
@@ -34,9 +34,9 @@ export async function POST(ctx: APIContext) {
   const jtiNew = crypto.randomUUID();
   const accessJwt = await signJwt(ctx, { sub: did, handle, t: 'access' }, 'access');
   const refreshJwt = await signJwt(ctx, { sub: did, handle, t: 'refresh', jti: jtiNew }, 'refresh');
-  if (jtiOld && ver.payload.exp && env.DB) {
-    await env.DB.exec('CREATE TABLE IF NOT EXISTS token_revocation (refresh_jti TEXT PRIMARY KEY, exp INTEGER NOT NULL);');
-    await env.DB.prepare('INSERT OR REPLACE INTO token_revocation (refresh_jti, exp) VALUES (?,?)').bind(jtiOld, Number(ver.payload.exp)).run();
+  if (jtiOld && ver.payload.exp && env.ALTERAN_DB) {
+    await env.ALTERAN_DB.exec('CREATE TABLE IF NOT EXISTS token_revocation (refresh_jti TEXT PRIMARY KEY, exp INTEGER NOT NULL);');
+    await env.ALTERAN_DB.prepare('INSERT OR REPLACE INTO token_revocation (refresh_jti, exp) VALUES (?,?)').bind(jtiOld, Number(ver.payload.exp)).run();
   }
   return Response.json({ did, handle, accessJwt, refreshJwt });
 }

package/src/lib/account-state.ts

@@ -0,0 +1,156 @@
+/**
+ * Finite-state machine for account lifecycle.
+ *
+ * The AT Protocol wire format encodes account status as two fields:
+ *   { active: boolean; status?: string }
+ *
+ * That representation lets you express illegal combinations (e.g.
+ * `active: true` paired with `status: "takendown"`). Internally we model
+ * the same domain as a discriminated union so the compiler enforces the
+ * invariant: every state is either active OR carries a specific reason
+ * for being inactive, never both. Conversion to the wire shape happens
+ * only at the firehose boundary.
+ */
+
+export type AccountState =
+  | { readonly tag: 'active' }
+  | { readonly tag: 'takendown' }
+  | { readonly tag: 'suspended'; readonly until?: string }
+  | { readonly tag: 'deactivated' }
+  | { readonly tag: 'deleted' };
+
+export type AccountStateTag = AccountState['tag'];
+
+const ACTIVE: AccountState = { tag: 'active' };
+const TAKENDOWN: AccountState = { tag: 'takendown' };
+const DEACTIVATED: AccountState = { tag: 'deactivated' };
+const DELETED: AccountState = { tag: 'deleted' };
+
+export type AccountEvent =
+  | { readonly tag: 'activate' }
+  | { readonly tag: 'takedown' }
+  | { readonly tag: 'suspend'; readonly until?: string }
+  | { readonly tag: 'deactivate' }
+  | { readonly tag: 'delete' };
+
+/**
+ * Apply an event to a state and return the next state.
+ *
+ * Illegal transitions (e.g. activating a deleted account) throw; this is a
+ * fail-fast contract so bugs surface at the call site instead of silently
+ * corrupting the firehose. Callers should validate authorization before
+ * passing an event to transition.
+ */
+export function transition(state: AccountState, event: AccountEvent): AccountState {
+  if (state.tag === 'deleted') {
+    throw new Error(`Account is deleted; cannot apply ${event.tag}`);
+  }
+  switch (event.tag) {
+    case 'activate':
+      return ACTIVE;
+    case 'takedown':
+      return TAKENDOWN;
+    case 'suspend':
+      return event.until ? { tag: 'suspended', until: event.until } : { tag: 'suspended' };
+    case 'deactivate':
+      return DEACTIVATED;
+    case 'delete':
+      return DELETED;
+  }
+}
+
+export type AccountWireStatus = {
+  readonly active: boolean;
+  readonly status?: string;
+};
+
+// The AT Protocol firehose #account event carries only { active, status } —
+// the spec has no slot for `until`. Wire round-trips through
+// fromWireStatus(toWireStatus) are intentionally lossy on the suspended
+// expiry; persistence uses toRow/fromRow which preserve the full FSM.
+export function toWireStatus(state: AccountState): AccountWireStatus {
+  switch (state.tag) {
+    case 'active':
+      return { active: true };
+    case 'takendown':
+      return { active: false, status: 'takendown' };
+    case 'suspended':
+      return { active: false, status: 'suspended' };
+    case 'deactivated':
+      return { active: false, status: 'deactivated' };
+    case 'deleted':
+      return { active: false, status: 'deleted' };
+  }
+}
+
+export function fromWireStatus(wire: AccountWireStatus): AccountState {
+  if (wire.active) return ACTIVE;
+  switch (wire.status) {
+    case 'takendown':
+      return TAKENDOWN;
+    case 'suspended':
+      return { tag: 'suspended' };
+    case 'deactivated':
+      return DEACTIVATED;
+    case 'deleted':
+      return DELETED;
+    default:
+      // Unknown / missing status from an older wire payload — treat as a
+      // suspended account so reads still gate but writes are blocked.
+      return { tag: 'suspended' };
+  }
+}
+
+export function isActive(state: AccountState): boolean {
+  return state.tag === 'active';
+}
+
+// Persistence shape. The account_state table mirrors this row exactly. We
+// keep both `active` (for legacy reads + cheap filters) and `status` /
+// `suspended_until` so the full FSM can be recovered from D1.
+export type AccountStateRow = {
+  readonly active: boolean;
+  readonly status: string | null;
+  readonly suspended_until: number | null;
+};
+
+export function toRow(state: AccountState): AccountStateRow {
+  switch (state.tag) {
+    case 'active':
+      return { active: true, status: null, suspended_until: null };
+    case 'takendown':
+      return { active: false, status: 'takendown', suspended_until: null };
+    case 'suspended':
+      return {
+        active: false,
+        status: 'suspended',
+        suspended_until: state.until ? Date.parse(state.until) : null,
+      };
+    case 'deactivated':
+      return { active: false, status: 'deactivated', suspended_until: null };
+    case 'deleted':
+      return { active: false, status: 'deleted', suspended_until: null };
+  }
+}
+
+export function fromRow(row: AccountStateRow): AccountState {
+  if (row.active) return ACTIVE;
+  switch (row.status) {
+    case 'takendown':
+      return TAKENDOWN;
+    case 'suspended': {
+      const until = row.suspended_until !== null
+        ? new Date(row.suspended_until).toISOString()
+        : undefined;
+      return until ? { tag: 'suspended', until } : { tag: 'suspended' };
+    }
+    case 'deleted':
+      return DELETED;
+    case 'deactivated':
+    default:
+      // null / unknown status with active=false is the bootstrap state for
+      // freshly-created accounts that haven't been activated yet. Treat it
+      // as deactivated so reads still gate but no special-case is needed.
+      return DEACTIVATED;
+  }
+}