@elytracms/studio 0.0.1

package/convex/content.ts

@@ -0,0 +1,316 @@
+import { documentKey, documentSchema } from '@elytracms/cms-core'
+import type {
+  CmsDocument,
+  CmsValidationIssue,
+  CollectionDef,
+  Locale,
+  LocaleConfig,
+  RedirectRecord,
+  RouteRecord,
+} from '@elytracms/cms-core'
+import { createContentClient, createContentContext, isDocumentHistory, rawDocument } from '@elytracms/content'
+import type {
+  ContentClient,
+  ContentContext,
+  ContentDocumentSource,
+  ContentLookup,
+  Perspective,
+} from '@elytracms/content'
+import type { AssetRecord } from '@elytracms/persistence'
+import { parseProjectGraph } from '@elytracms/project-graph'
+import type { ProjectGraph } from '@elytracms/project-graph'
+import type { QueryCtx } from './functions'
+
+/**
+ * EC-145 — the Convex-side content kit (vision AD-3/AD-4).
+ *
+ * Custom Convex functions are the query escape hatch ("our query language is
+ * TypeScript") — but only if developers never touch raw tables. `createContent`
+ * gives a Convex query function the same delivery surface as the Next-side
+ * accessors: `get`, `list`, `resolvePage`, plus the `raw` escape hatch, all
+ * with ambient `{ locale, perspective }` context.
+ *
+ * Byte-equivalence with the Next side is guaranteed by construction: the kit
+ * loads rows through `ctx.db`, builds the same synchronous `ContentLookup`
+ * that `@elytracms/next`'s snapshot builds from a `PersistenceAdapter`, and then
+ * runs the EXACT pure functions from `@elytracms/content`
+ * (`createContentClient` → `resolveDocument`, `query.ts` validation, cache
+ * tags). Nothing about resolution semantics is reimplemented here.
+ *
+ * Loading strategy (honest about v1 scale): the project's schema, documents,
+ * and asset metadata are prefetched ONCE per `createContent` call via the
+ * indexed `by_project` / `by_project_asset` scans, then every kit call is
+ * synchronous over memory — exactly like `createContentSnapshot` on the Next
+ * side. Filters and sorts therefore execute in-function over an indexed
+ * by-project fetch; see `contentIndexes.ts` for the index requirements this
+ * implies and the documented field-level-index upgrade path.
+ *
+ * Perspective isolation: the lookup holds the raw stored rows (draft state and
+ * all), and EVERY read path through `@elytracms/content` — `resolveDocument`,
+ * relation population, `listDocuments` filtering, slug fallback, and the `raw`
+ * escape hatch — applies the EC-142 perspective gate (`selectPerspective`)
+ * before any value is exposed. The kit never reads field values around that
+ * gate, so a `published` kit cannot observe draft values. (Pre-filtering draft
+ * rows out of the lookup would be redundant *and* would change structured
+ * issue messages — e.g. `unknown-relation-target` reasons — breaking
+ * byte-equivalence with the Next-side accessors.)
+ */
+
+const DEFAULT_LOCALES: LocaleConfig = { default: 'en', locales: ['en'] }
+
+/**
+ * Structured load-time problems (stored blobs that fail their canonical Zod
+ * schema, unparsable graph revisions). Never thrown — the kit degrades to the
+ * valid subset and reports what it skipped, mirroring the package-wide
+ * "structured issues, never crashes" stance.
+ *
+ * `invalid-stored-schema` is retained for wire/back-compat but is no longer
+ * produced: CMS collections are config-owned (EC-183, AD-11) and supplied by the
+ * caller (already validated), so there is no stored schema blob to reject.
+ */
+export type ContentKitIssueCode =
+  | 'invalid-stored-schema'
+  | 'invalid-stored-document'
+  | 'invalid-stored-graph'
+
+export interface ContentKitIssue {
+  code: ContentKitIssueCode
+  message: string
+  meta?: Record<string, unknown>
+}
+
+export interface CreateContentOptions {
+  projectId: string
+  /** Draft or published perspective (EC-021); ambient for every kit call. */
+  perspective: Perspective
+  /** Requested locale; defaults to the project's default locale. */
+  locale?: Locale
+  /** Override the locale config derived from the project settings. */
+  locales?: LocaleConfig
+  /**
+   * CMS collections (EC-183, AD-11), sourced from `elytra.config.ts` by the
+   * caller — the backend no longer stores a schema. Defaults to none (the kit
+   * then resolves documents with no collection structure).
+   */
+  collections?: readonly CollectionDef[]
+  /** Route records served by `resolvePage` (EC-019). */
+  routes?: readonly RouteRecord[]
+  /** Redirect records served by `resolvePage` (EC-019/020). */
+  redirects?: readonly RedirectRecord[]
+}
+
+export interface ContentKit {
+  /** The ambient `{ locale, perspective }` context every call resolves under. */
+  readonly context: ContentContext
+  /** Structured load-time issues (invalid stored blobs); never thrown. */
+  readonly loadIssues: readonly ContentKitIssue[]
+  /** Structural route issues from router construction (conflicts, loops). */
+  readonly routerIssues: readonly CmsValidationIssue[]
+  /** Delivery-shaped single-document accessor — same semantics as Next-side `getDocument`. */
+  readonly get: ContentClient['getDocument']
+  /** Delivery-shaped list accessor — same filter vocabulary as EC-143. */
+  readonly list: ContentClient['listDocuments']
+  /** Route → page/document resolution (EC-019), when routes were provided. */
+  readonly resolvePage: ContentClient['resolvePage']
+  /**
+   * Escape hatch (EC-142 `rawDocument`): the stored row, untouched — no locale
+   * fallback, no population, no asset resolution. The perspective gate still
+   * applies: a `published` kit never sees draft rows, even raw.
+   */
+  raw(collection: string, id: string): CmsDocument | null
+}
+
+/**
+ * Create the server-side content kit for one Convex query invocation.
+ *
+ * Usage inside a Convex query function:
+ * ```ts
+ * const content = await createContent(ctx, { projectId, perspective: 'published' })
+ * const { document: post } = content.get<Post>('post', slug)
+ * ```
+ */
+export async function createContent(
+  ctx: QueryCtx,
+  options: CreateContentOptions,
+): Promise<ContentKit> {
+  const { projectId, perspective } = options
+  const routes = options.routes ?? []
+  const redirects = options.redirects ?? []
+  const loadIssues: ContentKitIssue[] = []
+
+  // --- Prefetch (the only async part; everything below is synchronous) -----
+
+  // Config-first identity (EC-182/EC-183, AD-11): locales AND collections are
+  // supplied by the caller (sourced from `elytra.config.ts`); the backend has
+  // no `projects` row and no `cmsSchemas` table — it stores documents only.
+  const locales = options.locales ?? DEFAULT_LOCALES
+  const collectionDefs: CollectionDef[] = options.collections ? [...options.collections] : []
+
+  // One indexed scan over the project's documents (v1 scale; see module doc).
+  // A row's `document` is the continuous working **draft**; `publishedVersion`
+  // (when set) pins which recorded version is live — the Sanity model (EC-224).
+  const documentRows = await ctx.db.query('cmsDocuments').collect()
+
+  // The recorded version snapshots, indexed by (collection, docId, version), so
+  // a published read can serve the *pinned* version rather than the live draft.
+  const versionsByKey = new Map<string, Map<number, CmsDocument>>()
+  for (const row of await ctx.db.query('documentVersions').collect()) {
+    const parsed = documentSchema.safeParse(row.snapshot)
+    if (!parsed.success) continue
+    const key = `${row.collection}:${row.docId}`
+    let byVersion = versionsByKey.get(key)
+    if (!byVersion) {
+      byVersion = new Map()
+      versionsByKey.set(key, byVersion)
+    }
+    byVersion.set(row.version, parsed.data)
+  }
+
+  // Hybrid source per row (EC-224 A1a): a `publishedVersion` pointer yields a
+  // `DocumentHistory` (draft = the live row, published = the pinned snapshot),
+  // so the published perspective serves the recorded version, decoupled from
+  // the continuously-edited draft. An unpinned row stays a bare `CmsDocument`
+  // (the EC-142 gate reads its `state`) — backward-compatible: pre-pointer data
+  // resolves exactly as before.
+  const parsedSources: { key: string; source: ContentDocumentSource }[] = []
+  for (const row of documentRows) {
+    const parsed = documentSchema.safeParse(row.document)
+    if (!parsed.success) {
+      loadIssues.push({
+        code: 'invalid-stored-document',
+        message: `Stored document "${row.collection}:${row.docId}" does not match the canonical document schema and was skipped.`,
+        meta: { projectId, collection: row.collection, docId: row.docId },
+      })
+      continue
+    }
+    const draft = parsed.data
+    const key = documentKey(draft)
+    if (row.publishedVersion === undefined) {
+      parsedSources.push({ key, source: draft })
+      continue
+    }
+    // Pinned: serve the recorded snapshot for `published`. A dangling pin
+    // (version missing/invalid) under-serves to `null` — never the live draft.
+    const published = versionsByKey.get(`${row.collection}:${row.docId}`)?.get(row.publishedVersion)
+    parsedSources.push({ key, source: { draft, published, versions: [] } })
+  }
+  // Deterministic iteration order regardless of row creation order.
+  parsedSources.sort((a, b) => (a.key < b.key ? -1 : 1))
+
+  const assetRows = await ctx.db.query('assets').withIndex('by_asset').collect()
+  const assetRecords: AssetRecord[] = []
+  for (const row of assetRows) {
+    // EC-151 stores a stable serve URL on upload; older rows fall back to a
+    // live storage lookup, then to the blob adapter's placeholder convention.
+    const url = row.url ?? (await ctx.storage.getUrl(row.storageKey)) ?? undefined
+    assetRecords.push({
+      id: row.assetId,
+      // Single-tenant: rows no longer store projectId; the kit's `projectId`
+      // option (the constant slug) satisfies the AssetRecord shape (EC-179).
+      projectId,
+      filename: row.filename,
+      contentType: row.contentType,
+      byteSize: row.byteSize,
+      ...(row.width !== undefined ? { width: row.width } : {}),
+      ...(row.height !== undefined ? { height: row.height } : {}),
+      ...(row.alt !== undefined ? { alt: row.alt } : {}),
+      storageKey: row.storageKey,
+      ...(url !== undefined ? { url } : {}),
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+    })
+  }
+
+  // The page graph backs `resolvePage`'s page capability; it is only loaded
+  // when routes were provided (without routes, nothing can resolve to a page).
+  // Draft sees the latest revision; published sees the revision pinned to the
+  // publishing environment (EC-021 at the graph level).
+  let graph: ProjectGraph | null = null
+  if (routes.length > 0) {
+    let serialized: string | undefined
+    if (perspective === 'draft') {
+      const latest = await ctx.db
+        .query('graphRevisions')
+        .withIndex('by_revision')
+        .order('desc')
+        .first()
+      serialized = latest?.serializedGraph
+    } else {
+      const state = await ctx.db.query('publishingState').first()
+      const pinnedRevision = state?.status === 'published' ? state.publishedRevision : undefined
+      if (pinnedRevision !== undefined) {
+        const pinned = await ctx.db
+          .query('graphRevisions')
+          .withIndex('by_revision', (q) => q.eq('revision', pinnedRevision))
+          .first()
+        serialized = pinned?.serializedGraph
+      }
+    }
+    if (serialized !== undefined) {
+      const parsed = parseProjectGraph(serialized)
+      if (parsed.ok) {
+        graph = parsed.graph
+      } else {
+        loadIssues.push({
+          code: 'invalid-stored-graph',
+          message: `Stored graph revision for "${projectId}" (${perspective}) could not be parsed; pages are unavailable.`,
+          meta: { projectId, perspective },
+        })
+      }
+    }
+  }
+
+  // --- Index into the synchronous lookup the pure accessors read through ---
+
+  const collections = new Map<string, CollectionDef>()
+  for (const collection of collectionDefs) collections.set(collection.id, collection)
+
+  const documents = new Map<string, ContentDocumentSource>()
+  const byCollection = new Map<string, ContentDocumentSource[]>()
+  for (const { key, source } of parsedSources) {
+    documents.set(key, source)
+    const collection = isDocumentHistory(source) ? source.draft.collection : source.collection
+    const list = byCollection.get(collection) ?? []
+    list.push(source)
+    byCollection.set(collection, list)
+  }
+
+  const assets = new Map<string, AssetRecord>()
+  for (const record of assetRecords) assets.set(record.id, record)
+
+  const lookup: ContentLookup = {
+    collection: (id) => collections.get(id),
+    document: (ref) => documents.get(documentKey(ref)),
+    documents: (collectionId) => byCollection.get(collectionId) ?? [],
+    asset: (id) => assets.get(id),
+    // Same convention as `ConvexBlobStorage.url`: stored serve URL when
+    // available, otherwise the explicit unresolved-placeholder scheme.
+    assetUrl: (asset) => asset.url ?? `convex://storage/${asset.storageKey}`,
+  }
+
+  const context = createContentContext({
+    locale: options.locale ?? locales.default,
+    perspective,
+    locales,
+  })
+
+  // The EXACT pure client the Next-side accessors run — this is what makes
+  // results byte-equivalent across runtimes for the same inputs.
+  const client = createContentClient({ lookup, context, routes, redirects })
+
+  const raw = (collection: string, id: string): CmsDocument | null => {
+    const source = documents.get(documentKey({ collection, id }))
+    if (!source) return null
+    return rawDocument(context, source)
+  }
+
+  return {
+    context,
+    loadIssues,
+    routerIssues: client.routerIssues,
+    get: client.getDocument,
+    list: client.listDocuments,
+    resolvePage: client.resolvePage,
+    raw,
+  }
+}

package/convex/delivery.ts

@@ -0,0 +1,266 @@
+import { v } from 'convex/values'
+import { dataSourceSchema } from '@elytracms/data-binding'
+import { query } from './functions'
+import type { QueryCtx } from './functions'
+
+// EC-207: routes/redirects are config-sourced (authored in elytra.config.ts and
+// resolved by studio-core), NOT backend data. The delivery snapshot no longer
+// emits them and the `routes`/`redirects` CMS system collections are retired —
+// the host reads its route table from its own config (see
+// `apps/example-site/lib/content.ts` / `lib/live-content.ts`).
+
+/**
+ * EC-156 — the live delivery snapshot: everything a host app (e.g. the
+ * `@elytracms/next` example site) needs to assemble a `ContentSource` for one
+ * project, in a single query, fetchable over Convex's public HTTP query API
+ * (`POST {deployment}/api/query`) with plain `fetch` — no Convex client
+ * dependency in the host.
+ *
+ * ## Why `snapshot` is PUBLIC (deliberate, EC-150 exception)
+ *
+ * Every other project-scoped function in this deployment is guarded by
+ * `requireRole`. This one is not, on purpose: it serves **published content
+ * only** — the exact data the production website renders to every anonymous
+ * visitor. Publishing IS the act of making it public. The invariants that
+ * keep this safe are enforced server-side in this module:
+ *
+ * - each document is served as its published form before it leaves the
+ *   function — the EC-224 *pinned version snapshot* (decoupled from the live,
+ *   continuously-edited draft). Publish-ness is the version pointer alone;
+ *   drafts and unpinned rows are never returned;
+ * - the graph returned is ONLY the revision pinned by `publishingState` (the
+ *   deployment's single environment) — the latest working revision is never exposed;
+ * - nothing else draft-only exists in the payload (asset metadata has no draft
+ *   variant). CMS collection schema AND routes/redirects are config-owned
+ *   (EC-183/EC-207, AD-11) — the host reads them from its own config, not this
+ *   snapshot.
+ *
+ * `draftSnapshot` is the draft-perspective equivalent (latest graph revision,
+ * all stored document rows including drafts) and is gated by the deployment
+ * env var `DRAFT_PREVIEW_TOKEN` — set via `npx convex env set`. A missing or
+ * mismatching token throws `unauthorized`; an unset env var closes the
+ * endpoint entirely. The host server passes the token from its own env when
+ * Next draft mode is enabled (itself gated by the host's preview token).
+ */
+
+interface GraphRevisionPayload {
+  revision: number
+  serializedGraph: string
+}
+
+interface DeliverySnapshot {
+  projectId: string
+  perspective: 'published' | 'draft'
+  /**
+   * Data-source definitions the published graph's bindings reference (EC-166
+   * delivery): the builder persists its provisioned sources (per-section
+   * queries, per-template "current document" sources, provider refs) as
+   * documents in the `cms-data-sources` system collection; this surfaces them
+   * in the structural `CanvasDataSource` shape (`kind`/`id`/`label`/`config`)
+   * the host's payload materialization consumes. Sources are config, not
+   * content — perspective rules don't apply — but exposure is deliberate:
+   * only cms-kind query configs and provider-backed refs are returned (a
+   * rest-kind source's headers stay inside the deployment), and the captured
+   * sample/schema envelope (builder preview state) is not delivery data.
+   */
+  sources: unknown[]
+  /** Stored document rows visible in the perspective (published: pinned versions only). */
+  documents: unknown[]
+  /** Asset metadata in the delivery `AssetRecord` shape (with serve URLs). */
+  assets: unknown[]
+  /**
+   * Graph revisions per perspective. `snapshot` NEVER fills `draft` — only
+   * `draftSnapshot` does. `published` is the `publishingState`-pinned
+   * revision, or `null` when never published.
+   */
+  graphs: { draft: GraphRevisionPayload | null; published: GraphRevisionPayload | null }
+}
+
+/** One document per persisted source — must match the studio's sources-store. */
+const DATA_SOURCES_COLLECTION = 'cms-data-sources'
+
+/** The functionRef namespace marking a convex-kind source as provider-backed. */
+const PROVIDER_FUNCTION_PREFIX = 'provider:'
+
+/**
+ * Map the persisted `cms-data-sources` documents to the delivery `sources`
+ * array. Each record's `config` field carries the FULL canonical
+ * `@elytracms/data-binding` source, JSON-serialized; it is validated against
+ * `dataSourceSchema` (malformed records drop out, never crash the snapshot)
+ * and then deliberately projected to the structural delivery envelope:
+ *
+ * - `cms`-kind sources pass with their full query config (collection,
+ *   documentId, filter/sort/limit, locale) — exactly what
+ *   `materializeSourcePayloads` replays through `listDocuments`;
+ * - `convex`-kind sources pass only when provider-backed
+ *   (`functionRef: provider:<id>`) — a provider ref names project code, it
+ *   carries no secret;
+ * - `rest`-kind sources never leave the deployment (their headers could hold
+ *   credentials), and the captured sample/schema envelope (builder preview
+ *   state, not delivery config) is stripped for every kind.
+ */
+function dataSourcesFromSystemCollection(documents: unknown[]): unknown[] {
+  const sources: unknown[] = []
+  for (const document of documents) {
+    if (typeof document !== 'object' || document === null) continue
+    const row = document as { collection?: unknown; id?: unknown; values?: unknown }
+    if (row.collection !== DATA_SOURCES_COLLECTION) continue
+    const values = (typeof row.values === 'object' && row.values !== null ? row.values : {}) as {
+      config?: unknown
+    }
+    if (typeof values.config !== 'string') continue
+    let raw: unknown
+    try {
+      raw = JSON.parse(values.config)
+    } catch {
+      continue
+    }
+    const parsed = dataSourceSchema.safeParse(raw)
+    if (!parsed.success) continue
+    const source = parsed.data
+    if (source.kind === 'rest') continue
+    if (
+      source.kind === 'convex' &&
+      !source.config.functionRef.startsWith(PROVIDER_FUNCTION_PREFIX)
+    ) {
+      continue
+    }
+    sources.push({ kind: source.kind, id: source.id, label: source.label, config: source.config })
+  }
+  return sources
+}
+
+async function loadPinnedGraph(ctx: QueryCtx): Promise<GraphRevisionPayload | null> {
+  const state = await ctx.db.query('publishingState').first()
+  const pinned = state?.status === 'published' ? state.publishedRevision : undefined
+  if (pinned === undefined) return null
+  const row = await ctx.db
+    .query('graphRevisions')
+    .withIndex('by_revision', (q) => q.eq('revision', pinned))
+    .first()
+  return row ? { revision: row.revision, serializedGraph: row.serializedGraph } : null
+}
+
+async function loadLatestGraph(ctx: QueryCtx): Promise<GraphRevisionPayload | null> {
+  const row = await ctx.db.query('graphRevisions').withIndex('by_revision').order('desc').first()
+  return row ? { revision: row.revision, serializedGraph: row.serializedGraph } : null
+}
+
+export async function loadSnapshot(
+  ctx: QueryCtx,
+  args: { projectId: string },
+  perspective: 'published' | 'draft',
+): Promise<DeliverySnapshot> {
+  const { projectId } = args
+
+  const documentRows = await ctx.db.query('cmsDocuments').collect()
+  // THE published-content invariant (the trust boundary): the public snapshot
+  // ships ONLY published content — never a draft. Under the EC-224 pointer model
+  // a published row is served as its *pinned version snapshot* (decoupled from
+  // the continuously-edited draft); a row with no pin never leaves the
+  // deployment. Publish-ness is the pointer, full stop — there is no flat-state
+  // fallback (the `state` field is gone).
+  let documents: unknown[]
+  if (perspective === 'draft') {
+    documents = documentRows.map((row) => row.document as unknown)
+  } else {
+    const versionsByKey = new Map<string, Map<number, unknown>>()
+    for (const row of await ctx.db.query('documentVersions').collect()) {
+      const key = `${row.collection}:${row.docId}`
+      let byVersion = versionsByKey.get(key)
+      if (!byVersion) {
+        byVersion = new Map()
+        versionsByKey.set(key, byVersion)
+      }
+      byVersion.set(row.version, row.snapshot as unknown)
+    }
+    documents = []
+    for (const row of documentRows) {
+      if (row.publishedVersion === undefined) continue
+      // Serve the pinned recorded version, NOT the live draft. A dangling pin
+      // (version missing) is dropped — it never falls back to the draft.
+      const snapshot = versionsByKey
+        .get(`${row.collection}:${row.docId}`)
+        ?.get(row.publishedVersion)
+      if (snapshot !== undefined) documents.push(snapshot)
+    }
+  }
+
+  const assetRows = await ctx.db.query('assets').withIndex('by_asset').collect()
+  const assets: unknown[] = []
+  for (const row of assetRows) {
+    // Same URL convention as the EC-145 content kit: stored serve URL when
+    // available (EC-151), else a live storage lookup for older rows. Seeded
+    // rows carry a placeholder storage key that is not a real storage id —
+    // `getUrl` throws on those, so degrade to "no URL" instead of failing
+    // the whole snapshot (the host renders its explicit unresolved fallback).
+    const url = row.url ?? (await ctx.storage.getUrl(row.storageKey).catch(() => null)) ?? undefined
+    assets.push({
+      id: row.assetId,
+      // Wire-compat: the host still parses delivery assets with `projectId`
+      // (the constant slug from the snapshot args) until the host drops it (EC-179 §4).
+      projectId,
+      filename: row.filename,
+      contentType: row.contentType,
+      byteSize: row.byteSize,
+      ...(row.width !== undefined ? { width: row.width } : {}),
+      ...(row.height !== undefined ? { height: row.height } : {}),
+      ...(row.alt !== undefined ? { alt: row.alt } : {}),
+      storageKey: row.storageKey,
+      ...(url !== undefined ? { url } : {}),
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+    })
+  }
+
+  const published = await loadPinnedGraph(ctx)
+  // The latest working revision is loaded ONLY for the token-gated draft path.
+  const draft = perspective === 'draft' ? await loadLatestGraph(ctx) : null
+
+  // LIVE-mode data sources: the builder's persisted source records, projected
+  // to the delivery envelope (config only — see the helper's exposure rules).
+  // Sources are project *config*, not perspective-gated content, so they are
+  // extracted from every stored row (independent of publish state) — published
+  // bindings must always resolve their definitions, even when the defining
+  // `cms-data-sources` row is not itself "published".
+  const sources = dataSourcesFromSystemCollection(
+    documentRows.map((row) => row.document as unknown),
+  )
+
+  return {
+    projectId,
+    perspective,
+    sources,
+    documents,
+    assets,
+    graphs: { draft, published },
+  }
+}
+
+/**
+ * PUBLIC published-content snapshot — see the module header for why this is
+ * unguarded. Never returns draft document rows or unpinned graph revisions.
+ */
+export const snapshot = query({
+  args: { projectId: v.string() },
+  handler: async (ctx, args): Promise<DeliverySnapshot> => loadSnapshot(ctx, args, 'published'),
+})
+
+/**
+ * Draft-perspective snapshot for token-holding preview hosts: all stored
+ * document rows (drafts included) plus the latest working graph revision.
+ * Gated by the `DRAFT_PREVIEW_TOKEN` deployment env var.
+ */
+export const draftSnapshot = query({
+  args: { projectId: v.string(), token: v.string() },
+  handler: async (ctx, args): Promise<DeliverySnapshot> => {
+    const expected = process.env['DRAFT_PREVIEW_TOKEN']
+    if (expected === undefined || expected.length === 0) {
+      throw new Error('unauthorized: draft preview is not configured on this deployment')
+    }
+    if (args.token !== expected) {
+      throw new Error('unauthorized: invalid draft preview token')
+    }
+    return loadSnapshot(ctx, { projectId: args.projectId }, 'draft')
+  },
+})

package/convex/functions.ts

@@ -0,0 +1,35 @@
+import {
+  httpActionGeneric,
+  internalMutationGeneric,
+  internalQueryGeneric,
+  mutationGeneric,
+  queryGeneric,
+} from 'convex/server'
+import type {
+  DataModelFromSchemaDefinition,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  MutationBuilder,
+  QueryBuilder,
+} from 'convex/server'
+import schema from './schema'
+
+/**
+ * Typed function builders bound to our schema's data model. This is what Convex
+ * codegen normally writes into `_generated/server`; defining it explicitly lets
+ * the functions typecheck (and be reviewed in Git) without requiring a running
+ * deployment. `npx convex dev` will regenerate `_generated/*` for live use.
+ */
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>
+export type QueryCtx = GenericQueryCtx<DataModel>
+export type MutationCtx = GenericMutationCtx<DataModel>
+
+export const query = queryGeneric as QueryBuilder<DataModel, 'public'>
+export const mutation = mutationGeneric as MutationBuilder<DataModel, 'public'>
+/** CLI-/scheduler-only functions (e.g. seeding) — not callable by clients (EC-150). */
+export const internalMutation = internalMutationGeneric as MutationBuilder<DataModel, 'internal'>
+/** Server-only reads (e.g. the EC-157 HTTP sync endpoints) — not callable by clients. */
+export const internalQuery = internalQueryGeneric as QueryBuilder<DataModel, 'internal'>
+/** HTTP action builder (EC-252) — used by the package's `http.ts`/`sync.ts`. Not
+ * DataModel-bound: an action reaches data only through `ctx.runQuery`/`runMutation`. */
+export const httpAction = httpActionGeneric

package/convex/graphs.ts

@@ -0,0 +1,51 @@
+import { v } from 'convex/values'
+import { mutation, query } from './functions'
+import { requireRole } from './guard'
+
+/** Project graph + revision persistence (EC-041). Revisions are append-only. */
+
+export const saveRevision = mutation({
+  args: {
+    serializedGraph: v.string(),
+    schemaVersion: v.number(),
+    createdAt: v.string(),
+    label: v.optional(v.string()),
+    message: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    await requireRole(ctx, 'editor') // EC-150
+    // Compute the next revision atomically inside the mutation.
+    const last = await ctx.db.query('graphRevisions').withIndex('by_revision').order('desc').first()
+    const revision = (last?.revision ?? 0) + 1
+    const id = await ctx.db.insert('graphRevisions', { ...args, revision })
+    const record = await ctx.db.get(id)
+    return record
+  },
+})
+
+export const latest = query({
+  args: {},
+  handler: async (ctx) => {
+    await requireRole(ctx, 'viewer') // EC-150
+    return ctx.db.query('graphRevisions').withIndex('by_revision').order('desc').first()
+  },
+})
+
+export const revision = query({
+  args: { revision: v.number() },
+  handler: async (ctx, args) => {
+    await requireRole(ctx, 'viewer') // EC-150
+    return ctx.db
+      .query('graphRevisions')
+      .withIndex('by_revision', (q) => q.eq('revision', args.revision))
+      .first()
+  },
+})
+
+export const listRevisions = query({
+  args: {},
+  handler: async (ctx) => {
+    await requireRole(ctx, 'viewer') // EC-150
+    return ctx.db.query('graphRevisions').withIndex('by_revision').order('desc').collect()
+  },
+})