tapimo 0.0.2 → 0.1.0

package/src/db/Db.ts

@@ -0,0 +1,383 @@
+import {
+  CamelCasePlugin,
+  type Compilable,
+  CompiledQuery,
+  type Dialect,
+  Kysely,
+  PostgresDialect,
+  sql,
+} from 'kysely'
+import * as pg from 'pg'
+
+import type * as Organizations from './tables/organizations.js'
+import type * as VerifiedTokens from './tables/verifiedTokens.js'
+import type * as WebhookDeliveries from './tables/webhookDeliveries.js'
+import type * as WebhookSubscriptions from './tables/webhookSubscriptions.js'
+
+/**
+ * Kysely schema with camelCase columns. {@link CamelCasePlugin} maps table
+ * records, queries, and {@link migrations} DDL to snake_case storage columns.
+ */
+export type Database = {
+  migrations: {
+    appliedAt: string
+    checksum: string
+    name: string
+    /** SQL as applied; null on rows written before the column existed. */
+    sql: string | null
+  }
+  organizations: Organizations.Table
+  verified_token_lists: VerifiedTokens.ListTable
+  verified_tokens: VerifiedTokens.Table
+  webhook_deliveries: WebhookDeliveries.Table
+  webhook_subscriptions: WebhookSubscriptions.Table
+}
+
+/**
+ * A SQL-backed authoritative store: the underlying Kysely handle (table
+ * repository modules query through it), schema migrations, and transactions.
+ */
+export type Db = {
+  /** Closes the underlying connection/pool. */
+  close(): Promise<void>
+  /**
+   * Underlying Kysely handle. Transaction-scoped {@link Db} values carry the
+   * transaction handle, so repositories called with `tx` run inside it. */
+  kysely: Kysely<Database>
+  /** Applies any pending schema migrations; safe to call repeatedly and concurrently. */
+  migrate(): Promise<void>
+  /**
+   * Runs `fn` in a transaction — commits on return, rolls back on throw. `fn`
+   * receives a transaction-scoped {@link Db}; pass it (not the outer `Db`) to
+   * repositories so every query inside runs in the transaction.
+   */
+  transaction<value>(fn: (tx: Db) => Promise<value>): Promise<value>
+}
+
+/**
+ * A {@link Db}, or a factory for per-request Workers/Hyperdrive connections.
+ * Node can pass a long-lived singleton. Resolve at the leaf with {@link get}.
+ */
+export type Source = Db | (() => Db)
+
+/**
+ * Resolves a {@link Source} to a {@link Db}. Call at the request leaf so
+ * factories create per-request instances; singletons resolve to themselves.
+ *
+ * @param source - The database or factory.
+ * @returns The resolved {@link Db}.
+ */
+export function get(source: Source): Db {
+  return typeof source === 'function' ? source() : source
+}
+
+/**
+ * One schema migration. `up` builds a single idempotent Kysely DDL statement;
+ * {@link Db.migrate} compiles it for the checksum, then applies it.
+ */
+type Migration = {
+  /** Unique, ordered migration name (e.g. `0001_organizations`). */
+  name: string
+  /**
+   * Builds the migration's DDL against `db`. Use `.ifNotExists()` so the
+   * statement is safe to re-run without a wrapping transaction. */
+  up: (db: Kysely<Database>) => Compilable & { execute(): Promise<unknown> }
+}
+
+/**
+ * Ordered schema migrations for {@link Db.migrate}. Each `up` is one
+ * idempotent statement; compiled-SQL FNV-1a checksums reject edited applied
+ * migrations.
+ */
+export const migrations: readonly Migration[] = [
+  {
+    name: '0001_organizations',
+    up: (db) =>
+      db.schema
+        .createTable('organizations')
+        .ifNotExists()
+        .addColumn('id', 'text', (c) => c.primaryKey())
+        .addColumn('name', 'text', (c) => c.notNull())
+        .addColumn('createdBy', 'text')
+        .addColumn('createdAt', 'text', (c) => c.notNull())
+        .addColumn('updatedAt', 'text', (c) => c.notNull()),
+  },
+  {
+    name: '0002_webhook_subscriptions',
+    up: (db) =>
+      db.schema
+        .createTable('webhookSubscriptions')
+        .ifNotExists()
+        .addColumn('id', 'text', (c) => c.primaryKey())
+        .addColumn('ownerType', 'text', (c) => c.notNull())
+        .addColumn('ownerId', 'text', (c) => c.notNull())
+        .addColumn('chainId', 'integer', (c) => c.notNull())
+        .addColumn('eventType', 'text', (c) => c.notNull())
+        .addColumn('status', 'text', (c) => c.notNull().defaultTo('active'))
+        .addColumn('destination', 'jsonb', (c) => c.notNull())
+        .addColumn('filters', 'jsonb', (c) => c.notNull().defaultTo(sql`'{}'::jsonb`))
+        .addColumn('context', 'jsonb')
+        .addColumn('secret', 'text', (c) => c.notNull())
+        .addColumn('failureCount', 'integer', (c) => c.notNull().defaultTo(0))
+        .addColumn('lastDeliveryAt', 'text')
+        .addColumn('pollerCursor', 'text')
+        .addColumn('expiresAt', 'text')
+        .addColumn('createdAt', 'text', (c) => c.notNull())
+        .addColumn('updatedAt', 'text', (c) => c.notNull()),
+  },
+  {
+    name: '0003_webhook_deliveries',
+    up: (db) =>
+      db.schema
+        .createTable('webhookDeliveries')
+        .ifNotExists()
+        .addColumn('id', 'text', (c) => c.primaryKey())
+        .addColumn('subscriptionId', 'text', (c) =>
+          c.notNull().references('webhookSubscriptions.id').onDelete('cascade'),
+        )
+        .addColumn('eventId', 'text', (c) => c.notNull())
+        .addColumn('attempt', 'integer', (c) => c.notNull())
+        .addColumn('status', 'text', (c) => c.notNull())
+        .addColumn('requestUrl', 'text', (c) => c.notNull())
+        .addColumn('responseStatus', 'integer')
+        .addColumn('responseMs', 'integer')
+        .addColumn('error', 'text')
+        .addColumn('envelope', 'jsonb', (c) => c.notNull())
+        .addColumn('createdAt', 'text', (c) => c.notNull())
+        .addColumn('expiresAt', 'text', (c) => c.notNull()),
+  },
+  {
+    name: '0004_verified_token_lists',
+    up: (db) =>
+      db.schema
+        .createTable('verifiedTokenLists')
+        .ifNotExists()
+        .addColumn('chainId', 'integer', (c) => c.primaryKey())
+        .addColumn('version', 'text', (c) => c.notNull())
+        .addColumn('updatedAt', 'text', (c) => c.notNull()),
+  },
+  {
+    name: '0005_verified_tokens',
+    up: (db) =>
+      db.schema
+        .createTable('verifiedTokens')
+        .ifNotExists()
+        .addColumn('chainId', 'integer', (c) => c.notNull())
+        .addColumn('address', 'text', (c) => c.notNull())
+        .addColumn('symbol', 'text', (c) => c.notNull())
+        .addColumn('name', 'text', (c) => c.notNull())
+        .addColumn('currency', 'text', (c) => c.notNull())
+        .addColumn('decimals', 'integer', (c) => c.notNull())
+        .addColumn('logoUri', 'text')
+        .addColumn('position', 'integer', (c) => c.notNull())
+        .addPrimaryKeyConstraint('verified_tokens_pkey', ['chainId', 'address']),
+  },
+  {
+    // Case-insensitive symbol uniqueness per chain (`GET /tokens/:symbol`
+    // would otherwise be ambiguous).
+    name: '0006_verified_tokens_symbol_index',
+    up: (db) =>
+      db.schema
+        .createIndex('verified_tokens_symbol_idx')
+        .ifNotExists()
+        .unique()
+        .on('verifiedTokens')
+        .expression(sql`chain_id, lower(symbol)`),
+  },
+  {
+    // Owner list/count/cap scans and `id <` keyset paging.
+    name: '0007_webhook_subscriptions_owner_index',
+    up: (db) =>
+      db.schema
+        .createIndex('webhook_subscriptions_owner_idx')
+        .ifNotExists()
+        .on('webhookSubscriptions')
+        .columns(['ownerType', 'ownerId', 'id']),
+  },
+  {
+    // Partial index over active subscriptions: the poller's per-stream lookup.
+    // `sql.lit` keeps the predicate literal — DDL cannot carry parameters.
+    name: '0008_webhook_subscriptions_active_index',
+    up: (db) =>
+      db.schema
+        .createIndex('webhook_subscriptions_active_idx')
+        .ifNotExists()
+        .on('webhookSubscriptions')
+        .columns(['chainId', 'eventType'])
+        .where(sql.ref('status'), '=', sql.lit('active')),
+  },
+  {
+    name: '0009_webhook_subscriptions_expires_index',
+    up: (db) =>
+      db.schema
+        .createIndex('webhook_subscriptions_expires_idx')
+        .ifNotExists()
+        .on('webhookSubscriptions')
+        .column('expiresAt')
+        .where('expiresAt', 'is not', null),
+  },
+  {
+    // Per-subscription delivery-log paging.
+    name: '0010_webhook_deliveries_subscription_index',
+    up: (db) =>
+      db.schema
+        .createIndex('webhook_deliveries_subscription_idx')
+        .ifNotExists()
+        .on('webhookDeliveries')
+        .columns(['subscriptionId', 'id']),
+  },
+  {
+    name: '0011_webhook_deliveries_expires_index',
+    up: (db) =>
+      db.schema
+        .createIndex('webhook_deliveries_expires_idx')
+        .ifNotExists()
+        .on('webhookDeliveries')
+        .column('expiresAt'),
+  },
+]
+
+/**
+ * Builds a {@link Db} for any Kysely {@link Dialect}. All backends share
+ * migrations, repositories, and the required {@link CamelCasePlugin} mapping.
+ *
+ * @param dialect - The Kysely dialect for the target backend.
+ * @returns The database.
+ */
+export function from(dialect: Dialect): Db {
+  // Builds Db over a top-level Kysely handle or transaction-scoped Kysely handle.
+  function build(kysely: Kysely<Database>): Db {
+    // Prevents same-handle nested transactions from deadlocking capped pools.
+    // Nested work must use the callback's scoped `tx`.
+    let active = false
+    return {
+      async close() {
+        await kysely.destroy()
+      },
+      kysely,
+      async migrate() {
+        // A session advisory lock serializes the full run, including bootstrap
+        // DDL and ledger inserts. Pin one connection and unlock in `finally`.
+        await kysely.connection().execute(async (db) => {
+          await sql`SELECT pg_advisory_lock(${migrateLockKey})`.execute(db)
+          try {
+            await sql`CREATE TABLE IF NOT EXISTS migrations (name TEXT PRIMARY KEY, checksum TEXT NOT NULL, applied_at TEXT NOT NULL)`.execute(
+              db,
+            )
+            await sql`ALTER TABLE migrations ADD COLUMN IF NOT EXISTS sql TEXT`.execute(db)
+            const applied = new Map(
+              (await db.selectFrom('migrations').select(['name', 'checksum', 'sql']).execute()).map(
+                (row) => [row.name, row] as const,
+              ),
+            )
+            for (const migration of migrations) {
+              // Build once: compile (no I/O) for the checksum, execute to apply.
+              const statement = migration.up(db)
+              const compiled = statement.compile().sql
+              const digest = checksum(compiled)
+              const existing = applied.get(migration.name)
+              if (existing !== undefined) {
+                // The digest hashes kysely's rendered SQL, so a kysely upgrade
+                // can flip it with unchanged sources. The stored `sql` is what
+                // actually ran — diff it against the new render to tell render
+                // drift from a real edit (re-baseline procedure in AGENTS.md).
+                if (existing.checksum !== digest)
+                  throw new Error(
+                    `Migration "${migration.name}" was modified after being applied (checksum mismatch). Diff the migrations table's stored sql against the current render before re-baselining.`,
+                  )
+                // Backfill rows from before the column existed; the matching
+                // checksum proves the current render is what was applied.
+                if (existing.sql === null)
+                  await db
+                    .updateTable('migrations')
+                    .set({ sql: compiled })
+                    .where('name', '=', migration.name)
+                    .execute()
+                continue
+              }
+              await statement.execute()
+              await db
+                .insertInto('migrations')
+                .values({
+                  appliedAt: new Date().toISOString(),
+                  checksum: digest,
+                  name: migration.name,
+                  sql: compiled,
+                })
+                .execute()
+            }
+          } finally {
+            await sql`SELECT pg_advisory_unlock(${migrateLockKey})`.execute(db)
+          }
+        })
+      },
+      async transaction(fn) {
+        if (active) throw new Error('Db.transaction does not support nesting.')
+        active = true
+        try {
+          return await kysely.transaction().execute((trx) => fn(build(trx)))
+        } finally {
+          active = false
+        }
+      },
+    }
+  }
+  return build(new Kysely<Database>({ dialect, plugins: [new CamelCasePlugin()] }))
+}
+
+/**
+ * Creates a Postgres-backed {@link Db} via Kysely's `PostgresDialect`. Optional
+ * `schema` scopes every pooled connection and caps the pool for test isolation.
+ *
+ * @param options - Postgres options.
+ * @returns The database.
+ */
+export function postgres(options: postgres.Options): Db {
+  const { connectionString, schema } = options
+  const pool = new pg.Pool(schema ? { connectionString, max: 1 } : { connectionString })
+  return from(
+    new PostgresDialect({
+      pool,
+      ...(schema
+        ? {
+            onCreateConnection: async (connection) => {
+              await connection.executeQuery(
+                CompiledQuery.raw(`CREATE SCHEMA IF NOT EXISTS "${schema}"`),
+              )
+              await connection.executeQuery(CompiledQuery.raw(`SET search_path TO "${schema}"`))
+            },
+          }
+        : {}),
+    }),
+  )
+}
+
+export declare namespace postgres {
+  /** Options for {@link postgres}. */
+  type Options = {
+    /** Postgres connection string (`postgresql://…`). */
+    connectionString: string
+    /** Schema to create and scope the session to (isolates concurrent tests). */
+    schema?: string | undefined
+  }
+}
+
+/**
+ * Fixed key for the {@link Db.migrate} Postgres session advisory lock: the
+ * ASCII bytes of `"tapi"`, making all migrators serialize together.
+ */
+const migrateLockKey = 0x74617069
+
+/**
+ * Deterministic FNV-1a hash of migration SQL, so an applied migration whose
+ * source later changes is rejected (instead of silently diverging). Not
+ * cryptographic — only needs collision resistance for typos.
+ */
+function checksum(sql: string): string {
+  let hash = 0x811c9dc5
+  for (let i = 0; i < sql.length; i++) {
+    hash ^= sql.charCodeAt(i)
+    hash = Math.imul(hash, 0x01000193)
+  }
+  return (hash >>> 0).toString(16).padStart(8, '0')
+}

package/src/db/Schema.ts

@@ -0,0 +1,164 @@
+import * as z from 'zod/mini'
+
+import type * as Webhooks from '../internal/Webhooks.js'
+
+// Row schemas for database tables (`zod/mini`), the source of truth each
+// `tables/` module derives its `Table` type from. Nullable fields map to
+// nullable columns; the domain layer converts `null` back to absent fields.
+// Domain-owned unions and jsonb values stay typed by their owning module via
+// `z.custom` (type-only imports) so the two cannot drift.
+
+/** An organization, the top-level tenant that owns API keys. */
+export const Organization = z.object({
+  createdAt: z.string().check(z.describe('When the organization was created (ISO 8601).')),
+  createdBy: z
+    .nullable(z.string())
+    .check(z.describe('Identity that created the organization (e.g. admin email), or null.')),
+  id: z
+    .string()
+    .check(
+      z.describe('Opaque organization id (`org_…`).'),
+      z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+    ),
+  name: z
+    .string()
+    .check(z.describe('Human-readable organization name.'), z.meta({ examples: ['Acme, Inc.'] })),
+  updatedAt: z.string().check(z.describe('When the organization was last updated (ISO 8601).')),
+})
+
+/** Columns of the `organizations` table. */
+export type Organization = z.output<typeof Organization>
+
+/**
+ * A verified token: one row per curated token, ordered by `position` (list
+ * order is canonical and surfaced to clients). Addresses are stored lowercase;
+ * case-insensitive symbol uniqueness is enforced by a functional index on
+ * `lower(symbol)`.
+ */
+export const VerifiedToken = z.object({
+  address: z.string().check(z.describe('Verified TIP-20 token contract address (lowercase).')),
+  chainId: z.number().check(z.int(), z.describe('Chain the token belongs to.')),
+  currency: z.string().check(z.describe('Display currency, e.g. `USD`.')),
+  decimals: z.number().check(z.int(), z.describe('Decimal precision.')),
+  logoUri: z.nullable(z.string()).check(z.describe('Curated HTTPS logo URL, or null.')),
+  name: z.string().check(z.describe('Display name.')),
+  position: z
+    .number()
+    .check(z.int(), z.describe("Zero-based position in the chain's canonical list order.")),
+  symbol: z.string().check(z.describe('Ticker symbol.'), z.meta({ examples: ['USDC'] })),
+})
+
+/** Columns of the `verified_tokens` table. */
+export type VerifiedToken = z.output<typeof VerifiedToken>
+
+/**
+ * A chain's verified-token list metadata — the opaque `version` that drives
+ * the soft-refresh cache and `If-Match` preconditions, bumped on every publish.
+ */
+export const VerifiedTokenList = z.object({
+  chainId: z.number().check(z.int(), z.describe('Chain the list belongs to.')),
+  updatedAt: z.string().check(z.describe('ISO timestamp of the last publish.')),
+  version: z
+    .string()
+    .check(z.describe('Opaque list version (`<epoch-ms>_<hex>`); changes on every publish.')),
+})
+
+/** Columns of the `verified_token_lists` table. */
+export type VerifiedTokenList = z.output<typeof VerifiedTokenList>
+
+/**
+ * A webhook subscription. The `Webhooks.Owner` union maps to (`ownerType`,
+ * `ownerId`); jsonb object columns round-trip as parsed values. `pollerCursor`
+ * replaces the old per-subscription cursor key.
+ */
+export const WebhookSubscription = z.object({
+  chainId: z.number().check(z.int(), z.describe('Chain the subscription listens on.')),
+  context: z
+    .nullable(z.custom<Webhooks.Context>())
+    .check(z.describe('Human context (`jsonb`), or null.')),
+  createdAt: z.string().check(z.describe('ISO timestamp of creation.')),
+  destination: z
+    .custom<Webhooks.Destination>()
+    .check(z.describe('Delivery destination (`jsonb`).')),
+  eventType: z
+    .custom<Webhooks.EventType>()
+    .check(z.describe('Event type the subscription listens to.')),
+  expiresAt: z
+    .nullable(z.string())
+    .check(z.describe('ISO expiry timestamp (MPP-owned subscriptions), or null.')),
+  failureCount: z
+    .number()
+    .check(z.int(), z.describe('Consecutive delivery failures; drives auto-disable.')),
+  filters: z
+    .custom<Webhooks.Subscription['filters']>()
+    .check(z.describe('Event-type-specific filter predicates (`jsonb`).')),
+  id: z
+    .string()
+    .check(
+      z.describe('Subscription id (`wh_…`, lexically time-ordered).'),
+      z.meta({ examples: ['wh_0000019c1a2b3c4d5e6f7g8h'] }),
+    ),
+  lastDeliveryAt: z
+    .nullable(z.string())
+    .check(z.describe('ISO timestamp of the last successful delivery, or null.')),
+  ownerId: z
+    .string()
+    .check(z.describe('Owner identifier: `orgId` for `api_key` owners, `payer` for `mpp`.')),
+  ownerType: z.custom<Webhooks.Owner['type']>().check(z.describe('Owner kind.')),
+  pollerCursor: z
+    .nullable(z.string())
+    .check(z.describe('Poller keyset cursor, or null before the first tick.')),
+  secret: z.string().check(z.describe('HMAC signing secret.')),
+  status: z.custom<Webhooks.Status>().check(z.describe('Lifecycle status.')),
+  updatedAt: z
+    .string()
+    .check(z.describe('ISO timestamp of the last mutation (`pollerCursor` writes excluded).')),
+})
+
+/** Columns of the `webhook_subscriptions` table. */
+export type WebhookSubscription = z.output<typeof WebhookSubscription>
+
+/**
+ * A webhook delivery attempt. Rows are invisible past `expiresAt` (the
+ * retention deadline that replaces the old store TTL) and pruned by the
+ * poller; deleting a subscription cascades to its rows.
+ */
+export const WebhookDelivery = z.object({
+  attempt: z
+    .number()
+    .check(
+      z.int(),
+      z.describe('Consecutive attempt number (1-based) at the time of the delivery.'),
+    ),
+  createdAt: z.string().check(z.describe('ISO timestamp the attempt was recorded.')),
+  envelope: z
+    .custom<Webhooks.Envelope>()
+    .check(z.describe('The exact envelope that was sent (`jsonb`), for verbatim replay.')),
+  error: z
+    .nullable(z.string())
+    .check(z.describe('Failure reason when `status` is `failed`, or null.')),
+  eventId: z.string().check(z.describe('Idempotent event id the delivery carried (`evt_…`).')),
+  expiresAt: z
+    .string()
+    .check(z.describe('ISO retention deadline; rows past it are invisible and pruned.')),
+  id: z
+    .string()
+    .check(
+      z.describe('Delivery id (`whd_…`, lexically time-ordered).'),
+      z.meta({ examples: ['whd_0000019c1a2b3c4d5e6f7g8h'] }),
+    ),
+  requestUrl: z.string().check(z.describe('Subscriber callback URL the attempt targeted.')),
+  responseMs: z
+    .nullable(z.number())
+    .check(z.describe('Wall-clock duration of the attempt in ms, or null.')),
+  responseStatus: z
+    .nullable(z.number())
+    .check(z.describe('HTTP response status, or null when no response was received.')),
+  status: z.custom<Webhooks.DeliveryStatus>().check(z.describe('Outcome status.')),
+  subscriptionId: z
+    .string()
+    .check(z.describe('Owning subscription id (`wh_…`); FK with `ON DELETE CASCADE`.')),
+})
+
+/** Columns of the `webhook_deliveries` table. */
+export type WebhookDelivery = z.output<typeof WebhookDelivery>

package/src/db/tables/organizations.test.ts

@@ -0,0 +1,124 @@
+import { nanoid } from 'nanoid'
+
+import { postgresUrl } from '../../../test/containers.js'
+import * as Db from '../Db.js'
+import * as Organizations from './organizations.js'
+
+const create = () => Db.postgres({ connectionString: postgresUrl, schema: `t_${nanoid()}` })
+
+/** Redacts nondeterministic row fields (generated nanoid ids, timestamps). */
+function redact(record: Organizations.Record) {
+  return {
+    ...record,
+    createdAt: '<timestamp>',
+    id: /^org_[\w-]{21}$/.test(record.id) ? 'org_<id>' : record.id,
+    updatedAt: '<timestamp>',
+  }
+}
+
+describe('create', () => {
+  test('behavior: inserts with a generated id and defaults', async () => {
+    const db = create()
+    await db.migrate()
+    const record = await Organizations.create(db, { name: 'Acme, Inc.' })
+    expect(record.id).toMatch(/^org_/)
+    expect(redact(record)).toMatchInlineSnapshot(`
+      {
+        "createdAt": "<timestamp>",
+        "createdBy": null,
+        "id": "org_<id>",
+        "name": "Acme, Inc.",
+        "updatedAt": "<timestamp>",
+      }
+    `)
+    await db.close()
+  })
+
+  test('behavior: preserves an explicit id and createdBy', async () => {
+    const db = create()
+    await db.migrate()
+    const record = await Organizations.create(db, {
+      createdBy: 'admin@tempo.xyz',
+      id: 'org_explicit',
+      name: 'Explicit',
+    })
+    expect(redact(record)).toMatchInlineSnapshot(`
+      {
+        "createdAt": "<timestamp>",
+        "createdBy": "admin@tempo.xyz",
+        "id": "org_explicit",
+        "name": "Explicit",
+        "updatedAt": "<timestamp>",
+      }
+    `)
+    await db.close()
+  })
+})
+
+describe('get', () => {
+  test('behavior: returns undefined when absent', async () => {
+    const db = create()
+    await db.migrate()
+    expect(await Organizations.get(db, 'org_missing')).toBeUndefined()
+    await db.close()
+  })
+})
+
+describe('list', () => {
+  test('behavior: lists newest first', async () => {
+    const db = create()
+    await db.migrate()
+    await Organizations.create(db, { id: 'org_a', name: 'A' })
+    // Distinct createdAt for a deterministic order.
+    await new Promise((resolve) => setTimeout(resolve, 5))
+    await Organizations.create(db, { id: 'org_b', name: 'B' })
+    expect((await Organizations.list(db)).map((record) => record.id)).toMatchInlineSnapshot(`
+      [
+        "org_b",
+        "org_a",
+      ]
+    `)
+    await db.close()
+  })
+})
+
+describe('update', () => {
+  test('behavior: renames and bumps updatedAt', async () => {
+    const db = create()
+    await db.migrate()
+    const created = await Organizations.create(db, { id: 'org_1', name: 'Before' })
+    await new Promise((resolve) => setTimeout(resolve, 5))
+    const updated = await Organizations.update(db, 'org_1', { name: 'After' })
+    expect(updated?.name).toMatchInlineSnapshot(`"After"`)
+    expect(updated && updated.updatedAt > created.updatedAt).toBe(true)
+    await db.close()
+  })
+
+  test('behavior: returns undefined when absent', async () => {
+    const db = create()
+    await db.migrate()
+    expect(await Organizations.update(db, 'org_missing', { name: 'X' })).toBeUndefined()
+    await db.close()
+  })
+})
+
+describe('upsert', () => {
+  test('behavior: inserts when absent, defaulting name to the id', async () => {
+    const db = create()
+    await db.migrate()
+    await Organizations.upsert(db, { id: 'key_fallback' })
+    expect((await Organizations.get(db, 'key_fallback'))?.name).toMatchInlineSnapshot(
+      `"key_fallback"`,
+    )
+    await db.close()
+  })
+
+  test('behavior: leaves an existing row untouched', async () => {
+    const db = create()
+    await db.migrate()
+    await Organizations.create(db, { id: 'org_1', name: 'Original' })
+    await Organizations.upsert(db, { id: 'org_1', name: 'Clobbered' })
+    expect((await Organizations.get(db, 'org_1'))?.name).toMatchInlineSnapshot(`"Original"`)
+    await db.close()
+  })
+})