@elytracms/studio 0.0.92 → 0.0.94

package/convex/ingest.ts

@@ -0,0 +1,281 @@
+import { httpActionGeneric, makeFunctionReference } from 'convex/server'
+import type { FunctionReference, PublicHttpAction } from 'convex/server'
+import { v } from 'convex/values'
+import type { GenericId } from 'convex/values'
+import { z } from 'zod'
+import {
+  INGEST_MAX_BODY_BYTES,
+  INGEST_MAX_UPLOAD_BYTES,
+  INGEST_SIGNATURE_HEADER,
+  INGEST_UPLOAD_TTL_MS,
+  ingestPayloadSchema,
+  readIngestReceiverBody,
+  verifyIngestSignature,
+} from '@elytracms/core/ingest'
+import type { IngestHandlerResult, IngestPayload, IngestUploadClaim } from '@elytracms/core/ingest'
+import { defineRecordKind, resolveRecordQuery } from '@elytracms/core/persistence'
+import { createUuidIdFactory } from '@elytracms/core/determinism'
+import type { MutationCtx, QueryCtx } from './functions'
+import { findRecordDoc, listRecordWire, saveRecord } from './record-functions'
+
+/**
+ * EC-617 — the ONE inbound receiver of the public ingest seam (ruling EC-565 § 6c), and the
+ * helpers an addon's ingest handler is written with. A factory module: it registers no
+ * function itself — `defineStudioHttp({ auth, ingest })` (`http.ts`) mounts
+ * {@link ingestReceiver} at `INGEST_RECEIVER_PATH` (`POST /elytra/ingest`, an exact path).
+ *
+ * The receiver, per request:
+ *
+ * 1. `ELYTRA_INGEST_SECRET` unset → 401 `{ configured: false }` — closed until configured;
+ * 2. body over `INGEST_MAX_BODY_BYTES` → 413;
+ * 3. the HMAC (`x-elytra-signature: sha256=…`) verified in constant time with the
+ *    deployment's secret → 401 on anything else (the site's route signs with the same
+ *    value, `INGEST_SECRET`);
+ * 4. the envelope (`@elytracms/core/ingest`) → 400 with its issues;
+ * 5. the doctor's `probe` → 200 `{ ok: true, probe: true }`, nothing dispatched;
+ * 6. dispatch by kind to the handler the PROJECT registered — `event` / `submission`, and
+ *    `upload` to the submission handler (uploads are submission-scoped). A kind with no
+ *    handler is REFUSED (422, naming the kind) — never dropped: an `event` with no
+ *    analytics addon must fail visibly (EC-618's counsel gate relies on it);
+ * 7. an accepted `upload` gets ONE short-lived storage URL (`ctx.storage.generateUploadUrl`)
+ *    — the bytes go browser → storage, cross-origin by design; the submission that follows
+ *    claims the stored file with {@link claimIngestUpload}, which checks it against what the
+ *    upload request declared.
+ *
+ * The engine never imports an addon: the handler is an internal-mutation REFERENCE the
+ * consumer passes in its one `http.ts` line (`defineStudioHttp({ auth, ingest: {
+ * submission: formsIngest } })`), exported by the addon's `./convex` entry.
+ */
+
+/** What an ingest handler receives: the verified, parsed payload and the receipt time. */
+export const ingestHandlerArgs = { payload: v.any(), receivedAt: v.string() }
+
+/** An addon's ingest handler: an INTERNAL mutation (never client-callable). */
+export type IngestHandlerRef = FunctionReference<
+  'mutation',
+  'internal',
+  { payload: IngestPayload; receivedAt: string },
+  IngestHandlerResult
+>
+
+/**
+ * Name an addon's ingest handler for `defineStudioHttp({ ingest })` — its internal mutation by
+ * its module path (`ingestHandler('forms:ingest')`), the way every engine function is
+ * addressed (a string ref resolved against the consumer's deployment, EC-223). An addon
+ * exports the result from its `./convex` entry so the consumer writes no string.
+ */
+export function ingestHandler(name: `${string}:${string}`): IngestHandlerRef {
+  return makeFunctionReference<'mutation'>(name) as unknown as IngestHandlerRef
+}
+
+/** The handlers a project registers, by payload kind (`upload` goes to `submission`). */
+export interface IngestHandlers {
+  event?: IngestHandlerRef
+  submission?: IngestHandlerRef
+}
+
+/** Re-validate a handler's `payload` argument (it crossed a function boundary as `v.any()`). */
+export function parseIngestPayload(payload: unknown): IngestPayload {
+  return ingestPayloadSchema.parse(payload)
+}
+
+function json(status: number, body: Record<string, unknown>): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
+  })
+}
+
+function ingestSecret(): string | undefined {
+  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ?? {}
+  const value = env['ELYTRA_INGEST_SECRET']?.trim()
+  return value ? value : undefined
+}
+
+function utf8Length(text: string): number {
+  return new TextEncoder().encode(text).byteLength
+}
+
+/** The receiver `httpAction` (see the module header). */
+export function ingestReceiver(handlers: IngestHandlers = {}): PublicHttpAction {
+  return httpActionGeneric(async (ctx, request) => {
+    const secret = ingestSecret()
+    if (!secret) return json(401, { error: 'Ingest is not configured on this deployment.', configured: false })
+
+    const declared = Number(request.headers.get('content-length'))
+    if (Number.isFinite(declared) && declared > INGEST_MAX_BODY_BYTES) {
+      return json(413, { error: 'The payload is too large.' })
+    }
+    const raw = await request.text()
+    if (utf8Length(raw) > INGEST_MAX_BODY_BYTES) return json(413, { error: 'The payload is too large.' })
+
+    if (!(await verifyIngestSignature(raw, request.headers.get(INGEST_SIGNATURE_HEADER), secret))) {
+      return json(401, { error: 'Invalid or missing ingest signature.', configured: true })
+    }
+    const read = readIngestReceiverBody(raw)
+    if (!read.ok) return json(400, { error: read.message, ...(read.issues ? { issues: read.issues } : {}) })
+    const body = read.value
+    if (body.kind === 'probe') return json(200, { ok: true, probe: true })
+
+    const handlerKind = body.kind === 'upload' ? 'submission' : body.kind
+    const handler = handlers[handlerKind]
+    if (!handler) {
+      return json(422, {
+        error: `No handler is registered for "${body.kind}" ingest payloads on this deployment — install the addon that handles them and pass its handler to defineStudioHttp({ ingest }).`,
+        kind: body.kind,
+        handled: false,
+      })
+    }
+    const result = await ctx.runMutation(handler, { payload: body, receivedAt: new Date().toISOString() })
+    if (!result.ok) {
+      return json(result.status, { error: result.message, ...(result.issues ? { issues: result.issues } : {}) })
+    }
+    if (body.kind === 'upload') {
+      if (!result.uploadId) {
+        return json(500, { error: 'The submission handler accepted the upload but recorded no upload intent (recordIngestUpload).' })
+      }
+      const uploadUrl = await ctx.storage.generateUploadUrl()
+      return json(200, { ok: true, uploadId: result.uploadId, uploadUrl, expiresInSeconds: INGEST_UPLOAD_TTL_MS / 1000 })
+    }
+    return json(200, { ok: true, ...(result.id ? { id: result.id } : {}) })
+  })
+}
+
+// --- Submission-scoped uploads -------------------------------------------------------------
+//
+// The receiver issues a storage URL only for an upload a handler ACCEPTED and RECORDED as an
+// intent (`recordIngestUpload`); a submission CLAIMS it (`claimIngestUpload`), which checks the
+// stored file against the intent. Abuse is bounded by: the route's limiter and bot gate on every
+// URL issued, `INGEST_MAX_UPLOAD_BYTES` per file, the URL's one-hour life, the post-upload check
+// (an over-size or mistyped file is deleted, never kept), and the unclaimed intents an addon can
+// list (`unclaimedIngestUploads`) and surface. Convex returns the storage id to the uploader
+// only, so the bytes of an upload no submission ever claims cannot be located by the engine —
+// that is the documented residue, bounded by the limits above.
+
+/** The upload intent — an engine-internal record kind (no public functions). */
+export const ingestUploadRecordKind = defineRecordKind({
+  kind: 'ingestUpload',
+  module: 'ingest',
+  keys: ['target', 'state'],
+  time: 'issuedAt',
+  fields: {
+    target: z.string().min(1),
+    field: z.string().min(1),
+    contentType: z.string().min(1),
+    size: z.number().int().positive(),
+    state: z.enum(['issued', 'claimed', 'rejected']),
+    issuedAt: z.string().min(1),
+    storageId: z.string().optional(),
+  },
+})
+
+let mintUploadUuid: (() => string) | undefined
+
+export interface IngestUploadPolicy {
+  /** Largest accepted file in bytes (≤ `INGEST_MAX_UPLOAD_BYTES`). */
+  maxBytes?: number
+  /** Accepted content types (exact, or `image/*`-style prefixes). Absent → any. */
+  contentTypes?: readonly string[]
+}
+
+function typeAllowed(contentType: string, allowed: readonly string[] | undefined): boolean {
+  if (!allowed) return true
+  return allowed.some((entry) => (entry.endsWith('/*') ? contentType.startsWith(entry.slice(0, -1)) : entry === contentType))
+}
+
+/**
+ * Accept an `upload` payload under the handler's policy and record its intent. Returns the
+ * handler result to hand back to the receiver (`{ ok: true, uploadId }`, or a 413/415
+ * refusal). Call it from the submission handler's `upload` branch.
+ */
+export async function recordIngestUpload(
+  ctx: MutationCtx,
+  payload: Extract<IngestPayload, { kind: 'upload' }>,
+  receivedAt: string,
+  policy: IngestUploadPolicy = {},
+): Promise<IngestHandlerResult> {
+  const maxBytes = Math.min(policy.maxBytes ?? INGEST_MAX_UPLOAD_BYTES, INGEST_MAX_UPLOAD_BYTES)
+  if (payload.size > maxBytes) return { ok: false, status: 413, message: `The file is larger than ${maxBytes} bytes.` }
+  if (!typeAllowed(payload.contentType, policy.contentTypes)) {
+    return { ok: false, status: 415, message: `Files of type “${payload.contentType}” are not accepted here.` }
+  }
+  // EC-578: the one id factory (UUID v4 from crypto.getRandomValues) — never a clock or a counter.
+  mintUploadUuid ??= createUuidIdFactory()
+  const uploadId = `upload_${mintUploadUuid()}`
+  await saveRecord(
+    ctx,
+    ingestUploadRecordKind,
+    uploadId,
+    { ...payloadColumns(payload), state: 'issued', issuedAt: receivedAt },
+    { createdAt: receivedAt, updatedAt: receivedAt },
+  )
+  return { ok: true, uploadId }
+}
+
+function payloadColumns(payload: Extract<IngestPayload, { kind: 'upload' }>) {
+  return { target: payload.target, field: payload.field, contentType: payload.contentType, size: payload.size }
+}
+
+/** What a claim yields: the stored file's facts, or a refusal for the handler to return. */
+export type IngestUploadClaimResult =
+  | { ok: true; storageId: string; field: string; contentType: string; size: number }
+  | { ok: false; status: 409 | 413 | 415 | 422; message: string }
+
+/**
+ * Claim one upload for a submission to `target`: the intent must exist, be unclaimed,
+ * belong to `target`, be younger than `INGEST_UPLOAD_TTL_MS`, and the STORED file must match
+ * it (size ≤ declared, same content type). A mismatched file is deleted and the intent
+ * marked `rejected` — never kept.
+ */
+export async function claimIngestUpload(
+  ctx: MutationCtx,
+  claim: IngestUploadClaim,
+  target: string,
+  receivedAt: string,
+): Promise<IngestUploadClaimResult> {
+  const intent = await findRecordDoc(ctx, ingestUploadRecordKind, claim.uploadId)
+  const columns = intent?.data as
+    | { target: string; field: string; contentType: string; size: number; state: string; issuedAt: string }
+    | undefined
+  if (!columns || columns.target !== target) return { ok: false, status: 422, message: `Unknown upload “${claim.uploadId}”.` }
+  if (columns.state !== 'issued') return { ok: false, status: 409, message: `Upload “${claim.uploadId}” was already claimed.` }
+  if (Date.parse(receivedAt) - Date.parse(columns.issuedAt) > INGEST_UPLOAD_TTL_MS) {
+    return { ok: false, status: 422, message: `Upload “${claim.uploadId}” expired.` }
+  }
+  const storageId = claim.storageId as GenericId<'_storage'>
+  const file = await ctx.db.system.get(storageId).catch(() => null)
+  const stamps = { createdAt: receivedAt, updatedAt: receivedAt }
+  if (!file) return { ok: false, status: 422, message: `No stored file “${claim.storageId}”.` }
+  const refused =
+    file.size > columns.size
+      ? ({ status: 413, message: 'The stored file is larger than the upload declared.' } as const)
+      : (file.contentType ?? '') !== columns.contentType
+        ? ({ status: 415, message: 'The stored file is not of the declared type.' } as const)
+        : undefined
+  if (refused) {
+    await ctx.storage.delete(storageId)
+    await saveRecord(ctx, ingestUploadRecordKind, claim.uploadId, { state: 'rejected', storageId: claim.storageId }, stamps)
+    return { ok: false, ...refused }
+  }
+  await saveRecord(ctx, ingestUploadRecordKind, claim.uploadId, { state: 'claimed', storageId: claim.storageId }, stamps)
+  return { ok: true, storageId: claim.storageId, field: columns.field, contentType: columns.contentType, size: file.size }
+}
+
+/** Upload intents of `target` still unclaimed past their life — the visible orphan finding. */
+export async function unclaimedIngestUploads(
+  ctx: QueryCtx | MutationCtx,
+  target: string,
+  now: string,
+): Promise<{ uploadId: string; field: string; issuedAt: string }[]> {
+  const before = new Date(Date.parse(now) - INGEST_UPLOAD_TTL_MS).toISOString()
+  const rows = await listRecordWire(
+    ctx,
+    ingestUploadRecordKind,
+    resolveRecordQuery(ingestUploadRecordKind, { where: { target, state: 'issued' }, before }),
+  )
+  return rows.map((row) => ({
+    uploadId: String(row[ingestUploadRecordKind.idKey]),
+    field: String(row['field']),
+    issuedAt: String(row['issuedAt']),
+  }))
+}

package/convex/invites.ts

@@ -3,6 +3,7 @@ import { selectOrphanCredentialPurges } from '@elytracms/core/persistence'
 import { mutation, query } from './functions'
 import type { MutationCtx } from './functions'
 import { requireCapability } from './guard'
+import { assertAuthorityFloor, assertDeclaredRole } from './authority'
 
 /**
  * Invite allowlist management (EC-324). An admin invites an email + role; the
@@ -11,10 +12,14 @@ import { requireCapability } from './guard'
  * `requireCapability('project.administer')`, the same trust boundary as
  * member/user management; UI gating alone is never trusted.
  *
- * The invited `role` is validated against the active policy at the operations
- * write boundary (`invites.create` input); this store keeps it a lenient string
- * (schema-as-lens, EC-277). Keyed by normalized (lowercased) email; `create`
- * upserts so re-inviting the same email replaces the pending role.
+ * The invited `role` is validated against the project's policy at the operations
+ * write boundary (`invites.create`) AND here, against the DEPLOYED policy (EC-605 —
+ * `assertDeclaredRole`): an invite grants its role on consumption, so a role nobody
+ * declared must never be stored. Granting it is authority, so the integrity floor's
+ * "assign only roles you hold" applies too (`assertAuthorityFloor`, no target yet).
+ * The table keeps the role a lenient string (schema-as-lens, EC-277). Keyed by
+ * normalized (lowercased) email; `create` upserts so re-inviting the same email
+ * replaces the pending role.
  */
 
 const normalizeEmail = (email: string): string => email.trim().toLowerCase()
@@ -109,7 +114,10 @@ export const create = mutation({
     updatedAt: v.string(),
   },
   handler: async (ctx, args) => {
-    await requireCapability(ctx, 'project.administer')
+    const callerId = await requireCapability(ctx, 'project.administer')
+    // EC-605: only a declared role, and only one the inviter could grant themselves.
+    assertDeclaredRole(args.role)
+    await assertAuthorityFloor(ctx, { callerId, rolesGranted: [args.role], removesMembership: false })
     const email = normalizeEmail(args.email)
     // EC-358: never adopt orphan credentials — purge member-less auth rows for
     // this email atomically with the invite, so the invitee sets their own password.

package/convex/members.ts

@@ -1,7 +1,7 @@
 import { v } from 'convex/values'
 import { mutation, query } from './functions'
 import { getOptionalUserId, requireCapability, requireUserId } from './guard'
-import { assertAuthorityFloor, recordAuthorityAudit } from './authority'
+import { assertAuthorityFloor, assertDeclaredRole, recordAuthorityAudit } from './authority'
 
 /**
  * Deployment membership persistence (EC-150, single-tenant per EC-179). The
@@ -9,10 +9,13 @@ import { assertAuthorityFloor, recordAuthorityAudit } from './authority'
  * `ConvexMembersRepository` maps these onto `@elytracms/core/persistence` records.
  * Member *management* is admin-only, server-side — UI gating alone is never
  * trusted. One row per user grants their role on this deployment's one project.
+ *
+ * EC-605: a role is any string the DEPLOYED role policy declares (`./roles`) — the
+ * validator accepts a string and `set` refuses an undeclared one visibly
+ * (`assertDeclaredRole`), instead of the former literal admin|editor|viewer union,
+ * which made a project's own roles unwritable.
  */
 
-const roleValidator = v.union(v.literal('admin'), v.literal('editor'), v.literal('viewer'))
-
 export const list = query({
   args: {},
   handler: async (ctx) => {
@@ -62,7 +65,8 @@ export const mine = query({
 export const set = mutation({
   args: {
     userId: v.string(),
-    role: roleValidator,
+    /** One of the deployed policy's role ids — refused visibly otherwise (EC-605). */
+    role: v.string(),
     /**
      * Studio-user custom fields (EC-240, 240a). Optional so the member-management
      * path (`ConvexMembersRepository.setMember`) omits it; the users rail
@@ -75,6 +79,8 @@ export const set = mutation({
   },
   handler: async (ctx, args) => {
     const callerId = await requireCapability(ctx, 'project.administer')
+    // EC-605: only a role the deployed policy declares can be stored.
+    assertDeclaredRole(args.role)
     // Integrity floor (EC-240): can't demote the last admin / assign above self.
     // Throws `unauthorized: …` on denial — a first-class, visible error (verified
     // live). NOTE (EC-240 H-tail item 6): a denied attempt is NOT audited here. A

package/convex/orphan-hydration.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from 'vitest'
+import { convexTest } from 'convex-test'
+import type { ConvexHttpClient } from 'convex/browser'
+import type { FunctionReference } from 'convex/server'
+import type { CollectionDef } from '@elytracms/core/cms-core'
+import { createSequentialIdFactory } from '@elytracms/core/determinism'
+import { createOperations } from '@elytracms/core/operations'
+import { replaceAtCurrentRevision } from '@elytracms/core/persistence'
+import { ConvexPersistenceAdapter } from '../src/lib/persistence/convex-adapter'
+import { loadHydratedCms } from '../src/lib/operations/session-hydration'
+import schema from './schema'
+
+/**
+ * EC-606 close-out — the orphan count on the CONNECTED path, short of a signed-in
+ * connected studio (owner-run).
+ *
+ * The count itself is mode-independent: `loadHydratedCms` runs over whatever
+ * operations client the session has, and `project-session.test.tsx` already proves
+ * the content session carries its `orphans` to the rail foot. What only the connected
+ * mode adds is the backend between them — the real `cms:listDocuments` handler and the
+ * production `ConvexPersistenceAdapter`. This runs exactly that path on convex-test's
+ * in-memory backend (the harness of `contract-parity.test.ts`: the adapter's HTTP client
+ * is a call-through double onto `t.query` / `t.mutation`): a row of a collection the
+ * config does not declare must reach the session's orphan list, with its published
+ * count, and must not reach its documents.
+ */
+
+const modules = {
+  ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+  './_generated/api.ts': async () => ({}),
+}
+
+const PROJECT_ID = 'orphan-hydration'
+const SESSION_USER_ID = 'user_admin'
+
+const DECLARED: CollectionDef[] = [{ id: 'post', kind: 'document', fields: [{ name: 'title', type: 'text' }] }]
+
+interface AdapterBackend {
+  query: (ref: FunctionReference<'query'>, args: Record<string, unknown>) => Promise<unknown>
+  mutation: (ref: FunctionReference<'mutation'>, args: Record<string, unknown>) => Promise<unknown>
+}
+
+function asAdapterClient(backend: AdapterBackend): ConvexHttpClient {
+  return {
+    query: (ref: FunctionReference<'query'>, args?: Record<string, unknown>) => backend.query(ref, args ?? {}),
+    mutation: (ref: FunctionReference<'mutation'>, args?: Record<string, unknown>) => backend.mutation(ref, args ?? {}),
+  } as unknown as ConvexHttpClient
+}
+
+/** The production adapter over a fresh in-memory Convex backend, as the session admin. */
+async function connectedAdapter() {
+  const t = convexTest(schema, modules)
+  const now = '2026-10-26T00:00:00.000Z'
+  await t.run(async (ctx) => {
+    await ctx.db.insert('members', { userId: SESSION_USER_ID, role: 'admin', createdAt: now, updatedAt: now })
+  })
+  const asAdmin = t.withIdentity({ subject: SESSION_USER_ID, issuer: 'https://convex.test' })
+  return new ConvexPersistenceAdapter(asAdapterClient(asAdmin), PROJECT_ID)
+}
+
+/** The operations client a headless embedder (or the session) builds over that adapter. */
+function operationsOver(adapter: ConvexPersistenceAdapter) {
+  return createOperations({
+    adapter,
+    collections: () => DECLARED,
+    validateDocument: () => [],
+    idFactory: createSequentialIdFactory('doc'),
+  })
+}
+
+describe('EC-606 — orphans reach a connected session through the Convex functions', () => {
+  it('a stored row of an undeclared collection is counted (published too), and kept out of the documents', async () => {
+    const adapter = await connectedAdapter()
+    await replaceAtCurrentRevision(adapter.cms, PROJECT_ID, {
+      collection: 'post',
+      id: 'kept',
+      values: { title: 'Kept' },
+    })
+    await replaceAtCurrentRevision(adapter.cms, PROJECT_ID, {
+      collection: 'cms-data-sources',
+      id: 'legacy-draft',
+      values: { name: 'left behind by the data-binding subsystem' },
+    })
+    const published = await replaceAtCurrentRevision(adapter.cms, PROJECT_ID, {
+      collection: 'cms-data-sources',
+      id: 'legacy-live',
+      values: { name: 'and published' },
+    })
+    const pinned = await adapter.cms.publishDocument(
+      PROJECT_ID,
+      { collection: 'cms-data-sources', id: 'legacy-live' },
+      published.revision,
+    )
+    expect(pinned.status).toBe('ok')
+
+    const result = await loadHydratedCms(operationsOver(adapter), PROJECT_ID, DECLARED)
+    expect(result.ok).toBe(true)
+    if (!result.ok || !result.value) throw new Error('hydration must answer')
+    expect(result.value.orphans).toEqual([{ collection: 'cms-data-sources', count: 2, published: 1 }])
+    expect(result.value.documents.map((document) => `${document.collection}:${document.id}`)).toEqual(['post:kept'])
+  })
+
+  it('CONTROL: declared rows only → no orphans (the count is not a constant)', async () => {
+    const adapter = await connectedAdapter()
+    await replaceAtCurrentRevision(adapter.cms, PROJECT_ID, {
+      collection: 'post',
+      id: 'kept',
+      values: { title: 'Kept' },
+    })
+
+    const result = await loadHydratedCms(operationsOver(adapter), PROJECT_ID, DECLARED)
+    if (!result.ok || !result.value) throw new Error('hydration must answer')
+    expect(result.value.orphans).toEqual([])
+    expect(result.value.documents).toHaveLength(1)
+  })
+})

package/convex/rail-write-parity.test.ts

@@ -3,7 +3,7 @@ import { convexTest } from 'convex-test'
 import { makeFunctionReference } from 'convex/server'
 import type { ConvexHttpClient } from 'convex/browser'
 import type { FunctionReference } from 'convex/server'
-import { InMemoryPersistenceAdapter } from '@elytracms/core/persistence'
+import { InMemoryPersistenceAdapter, assetAlt } from '@elytracms/core/persistence'
 import type { PersistenceAdapter } from '@elytracms/core/persistence'
 import { ConvexPersistenceAdapter } from '../src/lib/persistence/convex-adapter'
 import { updateAssetMetadata } from '../src/components/assets/asset-metadata'
@@ -60,7 +60,6 @@ async function seedHero(adapter: PersistenceAdapter) {
     byteSize: 10,
     width: 4000,
     height: 2000,
-    alt: 'Harbour',
     title: 'Hero',
     focalPoint: { x: 0.2, y: 0.8 },
     thumb: THUMB,
@@ -69,17 +68,21 @@ async function seedHero(adapter: PersistenceAdapter) {
   })
 }
 
-/** "Reset to centre", then clear alt — the two connected clears that never persisted. */
+/**
+ * "Reset to centre", then clear alt — the two connected clears that never persisted.
+ * EC-587: the alt is cleared the way the options dialog clears it, by writing the bag
+ * without it (`meta.alt` is its one home).
+ */
 async function metadataClears(adapter: PersistenceAdapter) {
   await seedHero(adapter)
   const assets = adapter.assets
   const reset = await updateAssetMetadata({ assets }, PROJECT_ID, 'asset_hero', { focalPoint: null })
-  const clearedAlt = await updateAssetMetadata({ assets }, PROJECT_ID, 'asset_hero', { alt: '' })
+  const clearedAlt = await updateAssetMetadata({ assets }, PROJECT_ID, 'asset_hero', { meta: { legacyKey: 'kept' } })
   expect([reset.ok, clearedAlt.ok]).toEqual([true, true])
   const after = await adapter.assets.getAsset(PROJECT_ID, 'asset_hero')
   return {
     focalPoint: after.focalPoint ?? null,
-    alt: after.alt ?? null,
+    alt: assetAlt(after),
     title: after.title ?? null,
     thumb: after.thumb ?? null,
     lqip: after.lqip ?? null,
@@ -97,7 +100,7 @@ describe('EC-577 — the asset writers mean the same thing on both adapters', ()
       title: 'Hero',
       thumb: THUMB,
       lqip: LQIP,
-      meta: { alt: 'Harbour', legacyKey: 'kept' },
+      meta: { legacyKey: 'kept' },
     }
     expect({ memory, convex }).toEqual({ memory: expected, convex: expected })
   })
@@ -128,7 +131,7 @@ describe('EC-577 — the asset writers mean the same thing on both adapters', ()
         async get() {
           // An editor saves alt while the backfill is fetching this original — the
           // backfill's write lands after it, from a listing taken before it.
-          await updateAssetMetadata({ assets: adapter.assets }, PROJECT_ID, 'asset_big', { alt: 'Mid-run alt' })
+          await updateAssetMetadata({ assets: adapter.assets }, PROJECT_ID, 'asset_big', { meta: { alt: 'Mid-run alt' } })
           return new Uint8Array([1])
         },
       }
@@ -142,7 +145,7 @@ describe('EC-577 — the asset writers mean the same thing on both adapters', ()
       )
       expect(progress.generated).toBe(1)
       const after = await adapter.assets.getAsset(PROJECT_ID, 'asset_big')
-      expect([after.alt, after.thumb, after.lqip]).toEqual(['Mid-run alt', THUMB, LQIP])
+      expect([assetAlt(after), after.thumb, after.lqip]).toEqual(['Mid-run alt', THUMB, LQIP])
     }
   })
 })