mppx 0.8.12 → 0.8.14

package/src/cli/utils.test.ts

@@ -3,12 +3,35 @@ import { afterEach, describe, expect, test, vi } from 'vp/test'
 
 import {
   fetchTokenInfo,
+  isAgentEnvironment,
   networkRpcUrls,
   resolveChain,
   resolveFundingNetwork,
   resolveRpcUrl,
 } from './utils.js'
 
+describe('isAgentEnvironment', () => {
+  test('detects Claude Code', () => {
+    expect(isAgentEnvironment({ CLAUDECODE: '1' })).toBe(true)
+  })
+
+  test('detects Codex by exact env var', () => {
+    expect(isAgentEnvironment({ CODEX: '1' })).toBe(true)
+  })
+
+  test('detects Codex wrapper env vars', () => {
+    expect(isAgentEnvironment({ CODEX_CI: '1' })).toBe(true)
+    expect(isAgentEnvironment({ CODEX_SANDBOX: 'seatbelt' })).toBe(true)
+    expect(isAgentEnvironment({ CODEX_THREAD_ID: '019f6bc0-b80f-7061-ac1b-7af8ba1ea513' })).toBe(
+      true,
+    )
+  })
+
+  test('ignores empty and unrelated env vars', () => {
+    expect(isAgentEnvironment({ CODEX_CI: '', CI: '1' })).toBe(false)
+  })
+})
+
 describe('resolveRpcUrl', () => {
   afterEach(() => {
     delete process.env.MPPX_RPC_URL

package/src/cli/utils.ts

@@ -179,6 +179,16 @@ export function parseMethodOpts(raw: string | string[] | undefined): Record<stri
   return result
 }
 
+/** Returns true when the CLI is running inside an agent wrapper that prefers machine-readable output. */
+export function isAgentEnvironment(env: NodeJS.ProcessEnv = process.env): boolean {
+  if (env.CLAUDECODE) return true
+  for (const [key, value] of Object.entries(env)) {
+    if (!value) continue
+    if (key === 'CODEX' || key.startsWith('CODEX_')) return true
+  }
+  return false
+}
+
 export function isTempoAccount(accountName: string): boolean {
   return accountName.startsWith('tempo:')
 }

package/src/cli/validate/index.ts

@@ -1,9 +1,10 @@
 import { Cli, z } from 'incur'
 
 import { validate as validateCore, validateStream } from '../../validation/core.js'
-import { pc } from '../utils.js'
+import { isAgentEnvironment, pc } from '../utils.js'
 import type { Counts } from './helpers.js'
 import { printResults, printSection } from './helpers.js'
+import { missingDiscoverySuggestion } from './messages.js'
 
 const validate = Cli.create('validate', {
   description: 'Validate an MPP server implementation end-to-end',
@@ -22,7 +23,10 @@ const validate = Cli.create('validate', {
     header: z.array(z.string()).optional().describe('Request header (key:value, repeatable)'),
     verbose: z.number().default(0).meta({ count: true }).describe('Verbosity level'),
     yes: z.boolean().default(false).describe('Auto-approve mainnet payments'),
-    outputJson: z.boolean().default(false).describe('Output results as JSON'),
+    outputJson: z
+      .boolean()
+      .default(false)
+      .describe('Output results as JSON (auto-enabled in known agent environments)'),
   }),
   alias: {
     endpoint: 'e',
@@ -32,8 +36,10 @@ const validate = Cli.create('validate', {
     outputJson: 'j',
   },
   async run(c) {
+    const outputJson = c.options.outputJson || isAgentEnvironment()
+
     // JSON mode: batch everything
-    if (c.options.outputJson) {
+    if (outputJson) {
       const result = await validateCore({
         url: c.args.url,
         endpoint: c.options.endpoint,
@@ -82,17 +88,9 @@ const validate = Cli.create('validate', {
           discoveryFound = event.discovery.found
           if (!discoveryFound && !c.options.endpoint) {
             console.log('')
-            console.log(pc.yellow('  No discovery document found.'))
-            console.log(
-              pc.dim(
-                '  MPP servers must serve an OpenAPI document at /openapi.json with x-payment-info extensions.',
-              ),
-            )
-            console.log(
-              pc.dim(
-                '  To test a specific endpoint: mppx validate <url> --endpoint POST:/your/path',
-              ),
-            )
+            const [headline, ...lines] = missingDiscoverySuggestion.split('\n')
+            console.log(pc.yellow(`  ${headline}`))
+            for (const line of lines) console.log(line ? pc.dim(`  ${line}`) : '')
             console.log('')
             process.exit(1)
           }

package/src/cli/validate/messages.ts

@@ -0,0 +1,7 @@
+export const missingDiscoverySuggestion = [
+  'No discovery document found, endpoints could not be automatically found.',
+  'MPP servers must serve an OpenAPI document at /openapi.json with x-payment-info extensions.',
+  'The MPP SDKs can automatically expose this endpoint. See https://mpp.dev/sdk.',
+  '',
+  'To test a specific endpoint: mppx validate <url> --endpoint POST:/your/path',
+].join('\n')

package/src/cli/validate.test.ts

@@ -6,6 +6,10 @@ import * as Http from '~test/Http.js'
 import * as Challenge from '../Challenge.js'
 import * as Constants from '../Constants.js'
 import * as Receipt from '../Receipt.js'
+import { missingDiscoverySuggestion } from './validate/messages.js'
+
+// Keep validate tests out of JSON mode by default, even when the suite runs inside an agent.
+const isAgentEnvironmentMock = vi.fn(() => false)
 
 // Keep CLI orchestration tests independent of the public Tempo RPC and faucet.
 vi.doMock('viem/tempo', async () => {
@@ -28,11 +32,20 @@ vi.doMock('viem/actions', async () => {
   }
 })
 
+vi.doMock('./utils.js', async () => {
+  const actual = await vi.importActual<typeof import('./utils.js')>('./utils.js')
+  return {
+    ...actual,
+    isAgentEnvironment: isAgentEnvironmentMock,
+  }
+})
+
 // Auto-cleanup for test servers
 const servers: Http.TestServer[] = []
 afterEach(() => {
   servers.forEach((s) => s.close())
   servers.length = 0
+  isAgentEnvironmentMock.mockReturnValue(false)
 })
 
 async function testServer(handler: http.RequestListener) {
@@ -167,11 +180,8 @@ describe('validate: discovery', () => {
     })
     const { output, exitCode } = await serve(['validate', server.url])
     expect(exitCode).toBe(1)
-    expect(output).toContain('No discovery document found.')
-    expect(output).toContain('MPP servers must serve an OpenAPI document at /openapi.json')
-    expect(output).toContain(
-      'To test a specific endpoint: mppx validate <url> --endpoint POST:/your/path',
-    )
+    for (const line of missingDiscoverySuggestion.split('\n').filter(Boolean))
+      expect(output).toContain(line)
   })
 
   test('strips /openapi.json from input URL', { timeout: 15_000 }, async () => {
@@ -774,6 +784,19 @@ describe('validate: JSON mode', () => {
     expect(allPayment.every((r: { severity: string }) => r.severity === 'skip')).toBe(true)
   })
 
+  test(
+    'auto-enables JSON output when an agent environment is detected',
+    { timeout: 15_000 },
+    async () => {
+      const server = await mppServer(mainnetChallenge())
+      isAgentEnvironmentMock.mockReturnValue(true)
+      const { output } = await serve(['validate', server.url])
+      const result = parseJson(output)
+      expect(result.summary.skipped).toBeGreaterThan(0)
+      expect(result.endpoints.length).toBeGreaterThan(0)
+    },
+  )
+
   test('no console leaks before JSON', { timeout: 15_000 }, async () => {
     const server = await mppServer(mainnetChallenge())
     const { output } = await serve(['validate', server.url, '--outputJson', '--yes'])
@@ -791,4 +814,14 @@ describe('validate: JSON mode', () => {
     const result = parseJson(output)
     expect(Array.isArray(result.suggestions)).toBe(true)
   })
+
+  test('includes missing discovery suggestions', { timeout: 15_000 }, async () => {
+    const server = await testServer((_req, res) => {
+      res.writeHead(404)
+      res.end()
+    })
+    const { output } = await serve(['validate', server.url, '--outputJson'])
+    const result = parseJson(output)
+    expect(result.suggestions).toEqual([missingDiscoverySuggestion])
+  })
 })

package/src/client/Mppx.test-d.ts

@@ -262,9 +262,9 @@ describe('fetch context', () => {
     type FetchInit = NonNullable<Parameters<typeof _mppx.fetch>[1]>
     type Context = NonNullable<FetchInit['context']>
 
-    // Context is a union of charge and session contexts.
-    // `account` exists on both; `autoSwap` only on charge.
+    // Context is a union of charge and session contexts; both support auto-swap.
     expectTypeOf<Context>().toHaveProperty('account')
-    expectTypeOf<Extract<Context, { autoSwap?: unknown }>>().toHaveProperty('autoSwap')
+    expectTypeOf<Context>().toHaveProperty('autoSwap')
+    expectTypeOf<Context['autoSwap']>().toEqualTypeOf<AutoSwap.resolve.Value | undefined>()
   })
 })

package/src/client/internal/Fetch.ts

@@ -6,6 +6,7 @@ import type { MaybePromise } from '../../internal/types.js'
 import type * as Method from '../../Method.js'
 import type * as z from '../../zod.js'
 import * as Transport from '../Transport.js'
+import * as MethodChallenge from './MethodChallenge.js'
 import * as MethodResponse from './MethodResponse.js'
 
 // We tag wrappers with a global symbol so we can recognize wrappers created by mppx,
@@ -241,9 +242,22 @@ export function from<const methods extends readonly Method.AnyClient[]>(
         mi = selected.method
         if (challenge.expires) Expires.assert(challenge.expires, challenge.id)
 
+        const paymentInput = resolvePaymentRetryInput(
+          response,
+          initialRequest.input,
+          initialRequest.input,
+        )
         const createCredential = memoizeCreateCredential(
-          (overrideContext?: AnyContextFor<methods>) =>
-            resolveCredential(selectedChallenge, selected.method, overrideContext ?? context),
+          async (overrideContext?: AnyContextFor<methods>) => {
+            const credentialContext = overrideContext ?? context
+            await MethodChallenge.handle(selected.method, {
+              challenge: selectedChallenge,
+              context: credentialContext,
+              fetch: baseFetch,
+              input: paymentInput,
+            })
+            return resolveCredential(selectedChallenge, selected.method, credentialContext)
+          },
         )
         const eventCredential = await events.emit(
           'challenge.received',
@@ -278,11 +292,6 @@ export function from<const methods extends readonly Method.AnyClient[]>(
           }),
         )
 
-        const paymentInput = resolvePaymentRetryInput(
-          response,
-          initialRequest.input,
-          initialRequest.input,
-        )
         response = await baseFetch(
           paymentInput,
           transport.setCredential(

package/src/client/internal/MethodChallenge.ts

@@ -0,0 +1,30 @@
+import type * as Challenge from '../../Challenge.js'
+import type { MaybePromise } from '../../internal/types.js'
+import type * as Method from '../../Method.js'
+
+const handlers = new WeakMap<Method.AnyClient, Handler>()
+
+/** Inputs available before a client method creates a challenge credential. */
+export type HandlerParameters = {
+  challenge: Challenge.Challenge
+  context?: unknown
+  fetch: typeof globalThis.fetch
+  input: RequestInfo | URL
+}
+
+/** Internal client-method challenge hook. */
+export type Handler = (parameters: HandlerParameters) => MaybePromise<void>
+
+/** Registers an internal challenge hook without changing the public method shape. */
+export function register<const method extends Method.AnyClient>(
+  method: method,
+  handler: Handler,
+): method {
+  handlers.set(method, handler)
+  return method
+}
+
+/** Runs method-specific work before creating a challenge credential. */
+export function handle(method: Method.AnyClient, parameters: HandlerParameters): Promise<void> {
+  return Promise.resolve(handlers.get(method)?.(parameters))
+}

package/src/client/node.test.ts

@@ -0,0 +1,115 @@
+import { mkdtempSync, rmSync } from 'node:fs'
+import { homedir, tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+
+import { describe, expect, test } from 'vp/test'
+
+import type { ChannelEntry } from '../tempo/session/client/ChannelOps.js'
+import { entryKey } from '../tempo/session/client/ChannelStore.js'
+import { createSqliteChannelStore, defaultChannelDatabasePath } from './node.js'
+
+const channel: ChannelEntry = {
+  channelId: `0x${'11'.repeat(32)}`,
+  cumulativeAmount: 2_000_000n,
+  deposit: 10_000_000n,
+  descriptor: {
+    authorizedSigner: '0x0000000000000000000000000000000000000001',
+    expiringNonceHash: `0x${'22'.repeat(32)}`,
+    operator: '0x0000000000000000000000000000000000000000',
+    payee: '0x0000000000000000000000000000000000000002',
+    payer: '0x0000000000000000000000000000000000000003',
+    salt: `0x${'33'.repeat(32)}`,
+    token: '0x0000000000000000000000000000000000000004',
+  },
+  escrow: '0x0000000000000000000000000000000000000005',
+  chainId: 4217,
+  opened: true,
+}
+
+describe('SQLite ChannelStore', () => {
+  test('defaults to the shared Tempo wallet channels database', () => {
+    expect(defaultChannelDatabasePath()).toBe(join(homedir(), '.tempo', 'wallet', 'channels.db'))
+  })
+
+  test('persists a namespaced channel across fresh client instances', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'mppx-channels-'))
+    const path = join(directory, 'channels.db')
+    try {
+      const first = createSqliteChannelStore({ namespace: 'https://api.example.com', path })
+      first.set(channel)
+      first.close()
+
+      const second = createSqliteChannelStore({ namespace: 'https://api.example.com', path })
+      expect(second.get(entryKey(channel))).toEqual(channel)
+      second.set({ ...channel, cumulativeAmount: 1_000_000n, deposit: 5_000_000n })
+      expect(second.get(entryKey(channel))).toMatchObject({
+        cumulativeAmount: 2_000_000n,
+        deposit: 10_000_000n,
+      })
+      second.close()
+    } finally {
+      rmSync(directory, { recursive: true })
+    }
+  })
+
+  test('rehydrates an existing wallet-cli v2 channel row', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'mppx-wallet-channels-'))
+    const path = join(directory, 'channels.db')
+    try {
+      const database = new DatabaseSync(path)
+      database.exec(`CREATE TABLE channels (
+        channel_id TEXT PRIMARY KEY,
+        version INTEGER NOT NULL DEFAULT 1,
+        origin TEXT NOT NULL,
+        request_url TEXT NOT NULL DEFAULT '',
+        chain_id INTEGER NOT NULL,
+        escrow_contract TEXT NOT NULL,
+        token TEXT NOT NULL,
+        payee TEXT NOT NULL,
+        payer TEXT NOT NULL,
+        authorized_signer TEXT NOT NULL,
+        salt TEXT NOT NULL,
+        deposit TEXT NOT NULL,
+        cumulative_amount TEXT NOT NULL,
+        challenge_echo TEXT NOT NULL,
+        state TEXT NOT NULL DEFAULT 'active',
+        close_requested_at INTEGER NOT NULL DEFAULT 0,
+        grace_ready_at INTEGER NOT NULL DEFAULT 0,
+        created_at INTEGER NOT NULL,
+        last_used_at INTEGER NOT NULL,
+        accepted_cumulative TEXT NOT NULL DEFAULT '0',
+        server_spent TEXT NOT NULL DEFAULT '0',
+        session_protocol TEXT NOT NULL DEFAULT 'v1',
+        descriptor_json TEXT
+      )`)
+      database
+        .prepare(`INSERT INTO channels (
+          channel_id, origin, chain_id, escrow_contract, token, payee, payer,
+          authorized_signer, salt, deposit, cumulative_amount, challenge_echo,
+          state, created_at, last_used_at, session_protocol, descriptor_json
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, '{}', 'active', 1, 1, 'v2', ?)`)
+        .run(
+          channel.channelId,
+          'https://api.example.com',
+          channel.chainId,
+          channel.escrow,
+          channel.descriptor.token,
+          channel.descriptor.payee,
+          channel.descriptor.payer,
+          channel.descriptor.authorizedSigner,
+          channel.descriptor.salt,
+          channel.deposit.toString(),
+          channel.cumulativeAmount.toString(),
+          JSON.stringify(channel.descriptor),
+        )
+      database.close()
+
+      const store = createSqliteChannelStore({ namespace: 'https://api.example.com', path })
+      expect(store.get(entryKey(channel))).toEqual(channel)
+      store.close()
+    } finally {
+      rmSync(directory, { recursive: true })
+    }
+  })
+})

package/src/client/node.ts

@@ -0,0 +1,247 @@
+import { mkdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+
+import type { ChannelEntry } from '../tempo/session/client/ChannelOps.js'
+import {
+  deserializeEntry,
+  entryKey,
+  serializeEntry,
+  type ChannelStore,
+  type StoredChannel,
+} from '../tempo/session/client/ChannelStore.js'
+
+const schemaVersion = 2
+
+/** Options for the Node SQLite-backed payer channel store. */
+export type SqliteChannelStoreOptions = {
+  /** Service namespace, normally the protected API origin. */
+  namespace?: string | undefined
+  /** SQLite file path. Defaults to Tempo Wallet's shared channel database. */
+  path?: string | undefined
+  /** Full protected URL retained for CLI session-management requests. */
+  requestUrl?: string | undefined
+}
+
+/** A SQLite-backed channel store that can release its database handle. */
+export type SqliteChannelStore = ChannelStore & {
+  /** Absolute or caller-supplied path opened by this store. */
+  readonly path: string
+  /** Closes the underlying SQLite connection. */
+  close(): void
+}
+
+type ChannelRow = {
+  chain_id: number
+  channel_id: string
+  cumulative_amount: string
+  deposit: string
+  descriptor_json: string | null
+  entry_json: string | null
+  escrow_contract: string
+  state: string
+}
+
+/** Returns the channel database shared by Tempo command-line applications. */
+export function defaultChannelDatabasePath(): string {
+  return join(homedir(), '.tempo', 'wallet', 'channels.db')
+}
+
+/**
+ * Creates a synchronous Node SQLite implementation of {@link ChannelStore}.
+ *
+ * The schema is compatible with Tempo Wallet's existing `channels` table, so
+ * a fresh MPPx client can reuse v2 session records without a separate migration
+ * command. A namespace keeps identical payment scopes at different services
+ * isolated from one another.
+ */
+export function createSqliteChannelStore(
+  options: SqliteChannelStoreOptions = {},
+): SqliteChannelStore {
+  const path = options.path ?? defaultChannelDatabasePath()
+  const namespace = options.namespace ?? ''
+  const requestUrl = options.requestUrl ?? namespace
+  const origin = resolveOrigin(requestUrl, namespace)
+  mkdirSync(dirname(path), { recursive: true })
+  const database = new DatabaseSync(path)
+  database.exec('PRAGMA journal_mode = WAL')
+  database.exec('PRAGMA busy_timeout = 5000')
+  ensureSchema(database)
+
+  const getRow = database.prepare(`SELECT channel_id, chain_id, escrow_contract,
+      cumulative_amount, deposit, descriptor_json, entry_json, state
+    FROM channels
+    WHERE scope_key = ?`)
+  const deleteScope = database.prepare('DELETE FROM channels WHERE scope_key = ?')
+  const deleteOtherScopeChannel = database.prepare(
+    'DELETE FROM channels WHERE scope_key = ? AND channel_id <> ?',
+  )
+  const upsert = database.prepare(`INSERT INTO channels (
+      channel_id, version, scope_key, origin, request_url, chain_id, escrow_contract, token,
+      payee, payer, authorized_signer, salt, session_protocol, descriptor_json, entry_json,
+      deposit, cumulative_amount, accepted_cumulative, challenge_echo, state,
+      close_requested_at, grace_ready_at, created_at, last_used_at, server_spent
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'v2', ?, ?, ?, ?, '0', '{}', 'active',
+      0, 0, ?, ?, '0')
+    ON CONFLICT(channel_id) DO UPDATE SET
+      version = excluded.version,
+      scope_key = excluded.scope_key,
+      origin = excluded.origin,
+      request_url = excluded.request_url,
+      chain_id = excluded.chain_id,
+      escrow_contract = excluded.escrow_contract,
+      token = excluded.token,
+      payee = excluded.payee,
+      payer = excluded.payer,
+      authorized_signer = excluded.authorized_signer,
+      salt = excluded.salt,
+      session_protocol = excluded.session_protocol,
+      descriptor_json = excluded.descriptor_json,
+      entry_json = excluded.entry_json,
+      deposit = excluded.deposit,
+      cumulative_amount = excluded.cumulative_amount,
+      state = 'active',
+      close_requested_at = 0,
+      last_used_at = excluded.last_used_at`)
+
+  return {
+    path,
+    get(key) {
+      const row = getRow.get(scopedKey(namespace, key)) as ChannelRow | undefined
+      return row ? entryFromRow(row) : undefined
+    },
+    set(entry) {
+      const scopeKey = scopedKey(namespace, entryKey(entry))
+      database.exec('BEGIN IMMEDIATE')
+      try {
+        const existing = getRow.get(scopeKey) as ChannelRow | undefined
+        const merged = mergeEntry(existing ? entryFromRow(existing) : undefined, entry)
+        const stored = serializeEntry(merged)
+        const now = Math.floor(Date.now() / 1_000)
+        deleteOtherScopeChannel.run(scopeKey, merged.channelId)
+        upsert.run(
+          merged.channelId,
+          schemaVersion,
+          scopeKey,
+          origin,
+          requestUrl,
+          merged.chainId,
+          merged.escrow,
+          merged.descriptor.token,
+          merged.descriptor.payee,
+          merged.descriptor.payer,
+          merged.descriptor.authorizedSigner,
+          merged.descriptor.salt,
+          JSON.stringify(merged.descriptor),
+          JSON.stringify(stored),
+          merged.deposit.toString(),
+          merged.cumulativeAmount.toString(),
+          now,
+          now,
+        )
+        database.exec('COMMIT')
+      } catch (error) {
+        database.exec('ROLLBACK')
+        throw error
+      }
+    },
+    delete(key) {
+      deleteScope.run(scopedKey(namespace, key))
+    },
+    close() {
+      database.close()
+    },
+  }
+}
+
+function resolveOrigin(requestUrl: string, fallback: string): string {
+  try {
+    return new URL(requestUrl).origin
+  } catch {
+    return fallback
+  }
+}
+
+function scopedKey(namespace: string, key: string): string {
+  return `${namespace}\n${key}`
+}
+
+function mergeEntry(current: ChannelEntry | undefined, incoming: ChannelEntry): ChannelEntry {
+  if (!current || current.channelId.toLowerCase() !== incoming.channelId.toLowerCase())
+    return incoming
+  return {
+    ...incoming,
+    cumulativeAmount:
+      current.cumulativeAmount > incoming.cumulativeAmount
+        ? current.cumulativeAmount
+        : incoming.cumulativeAmount,
+    deposit: current.deposit > incoming.deposit ? current.deposit : incoming.deposit,
+  }
+}
+
+function entryFromRow(row: ChannelRow): ChannelEntry {
+  if (row.entry_json) {
+    const stored = JSON.parse(row.entry_json) as StoredChannel
+    return deserializeEntry({ ...stored, opened: row.state === 'active' })
+  }
+
+  if (!row.descriptor_json) throw new Error('v2 channel row is missing its descriptor')
+  const descriptor = JSON.parse(row.descriptor_json) as ChannelEntry['descriptor']
+  return {
+    channelId: row.channel_id as ChannelEntry['channelId'],
+    cumulativeAmount: BigInt(row.cumulative_amount),
+    deposit: BigInt(row.deposit),
+    descriptor,
+    escrow: row.escrow_contract as ChannelEntry['escrow'],
+    chainId: row.chain_id,
+    opened: row.state === 'active',
+  }
+}
+
+function ensureSchema(database: DatabaseSync): void {
+  database.exec(`CREATE TABLE IF NOT EXISTS channels (
+    channel_id TEXT PRIMARY KEY,
+    version INTEGER NOT NULL DEFAULT 1,
+    scope_key TEXT,
+    origin TEXT NOT NULL,
+    request_url TEXT NOT NULL DEFAULT '',
+    chain_id INTEGER NOT NULL,
+    escrow_contract TEXT NOT NULL,
+    token TEXT NOT NULL,
+    payee TEXT NOT NULL,
+    payer TEXT NOT NULL,
+    authorized_signer TEXT NOT NULL,
+    salt TEXT NOT NULL,
+    deposit TEXT NOT NULL,
+    cumulative_amount TEXT NOT NULL,
+    challenge_echo TEXT NOT NULL,
+    state TEXT NOT NULL DEFAULT 'active',
+    close_requested_at INTEGER NOT NULL DEFAULT 0,
+    grace_ready_at INTEGER NOT NULL DEFAULT 0,
+    created_at INTEGER NOT NULL,
+    last_used_at INTEGER NOT NULL,
+    accepted_cumulative TEXT NOT NULL DEFAULT '0',
+    server_spent TEXT NOT NULL DEFAULT '0',
+    session_protocol TEXT NOT NULL DEFAULT 'v1',
+    descriptor_json TEXT,
+    entry_json TEXT
+  )`)
+  addColumn(database, 'scope_key TEXT')
+  addColumn(database, 'entry_json TEXT')
+  database.exec(`UPDATE channels
+    SET scope_key = origin || char(10) || lower(payee) || ':' || lower(token) || ':' ||
+      lower(escrow_contract) || ':' || chain_id
+    WHERE scope_key IS NULL AND session_protocol = 'v2' AND descriptor_json IS NOT NULL`)
+  database.exec(
+    'CREATE UNIQUE INDEX IF NOT EXISTS idx_channels_scope_key ON channels(scope_key) WHERE scope_key IS NOT NULL',
+  )
+  database.exec('CREATE INDEX IF NOT EXISTS idx_channels_origin ON channels(origin)')
+}
+
+function addColumn(database: DatabaseSync, definition: string): void {
+  const name = definition.slice(0, definition.indexOf(' '))
+  const columns = database.prepare('PRAGMA table_info(channels)').all() as Array<{ name: string }>
+  if (columns.some((column) => column.name === name)) return
+  database.exec(`ALTER TABLE channels ADD COLUMN ${definition}`)
+}

package/src/internal/types.test-d.ts

@@ -0,0 +1,21 @@
+import { expectTypeOf, test } from 'vp/test'
+
+import type { ConfiguredDefaults } from './types.js'
+
+test('ConfiguredDefaults retains only known defined values', () => {
+  type Parameters = {
+    configured: string
+    maybeDefined?: number | undefined
+    explicitlyUndefined: boolean | undefined
+    unrelated: bigint
+  }
+  type Defaults = {
+    configured?: string | undefined
+    maybeDefined?: number | undefined
+    explicitlyUndefined?: boolean | undefined
+  }
+
+  expectTypeOf<ConfiguredDefaults<Parameters, Defaults>>().toEqualTypeOf<{
+    configured: string
+  }>()
+})