lecodes-sdk 2.0.6 → 2.0.8

package/package.json

@@ -42,9 +42,10 @@
     "@types/node": "^25.9.1",
     "typescript": "~5.8.3",
     "gl-matrix": "^3.4.4",
-    "marcidb-embedded": "^0.13.0"
+    "marcidb-embedded": "^0.14.1",
+    "sharp": "^0.35.2"
   },
-  "version": "2.0.6",
+  "version": "2.0.8",
   "files": [
     "src",
     "dist",

package/src/compile/libraryImports.ts

@@ -31,6 +31,15 @@ export const rewriteLibraryImports = (src: string, slugs: Set<string>): string =
     if (isRelativeOrAbsolute(spec)) return spec
     const slash = spec.indexOf("/")
     const slug = slash === -1 ? spec : spec.slice(0, slash)
+    // The SDK's plugin bases (`lecodes-sdk/plugin`: ServiceChannel, ViewChannel — what a plugin's
+    // generated wrapper extends): the one SDK module a PROJECT file may import, because a plugin of
+    // the project itself (`plugins/<id>/sdk/<id>.gen.ts`, written by `lecodes plugin gen`) lives in
+    // the project tree and not in the SDK. It is the SDK's own module under /__sdk, the same instance
+    // the vendored first-party wrappers reach by relative path. Anything else of the SDK is a global.
+    if (slug === "lecodes-sdk") {
+      if (spec === "lecodes-sdk/plugin" || spec.startsWith("lecodes-sdk/plugin/")) return `/__sdk${spec.slice("lecodes-sdk".length)}`
+      throw new Error(`import from "${spec}": the SDK needs no imports — its API is globals; only "lecodes-sdk/plugin" (a plugin wrapper's bases) is imported.`)
+    }
     if (slugs.has(slug)) {
       // `acme-ui` → `/__lib/acme-ui/index`; `acme-ui/theme` → `/__lib/acme-ui/theme`.
       const sub = slash === -1 ? "/index" : spec.slice(slash)

package/src/compile/serverTypes.ts

@@ -127,6 +127,8 @@ const wrongSideGlobals = (ts: TS, program: import("typescript").Program, checker
   return out
 }
 
+const FILE_TYPE_PATH = "/__lecodes/file.d.ts"
+
 export type DeriveResult = {
   /** endpoint id → parameter schemas (only endpoints the checker could see). */
   params: Record<string, ParamSchema[]>
@@ -152,6 +154,9 @@ export const deriveEndpointParams = async (entries: CompileEntry[], modules: Rec
     if (!/\.[tj]sx?$/.test(e.path)) continue
     files.set(normalizePath(e.path), e.text)
   }
+  // The one SDK type this program knows: a parameter typed `File` is an upload, and has to be told
+  // from "some object". A declaration of the type alone — as a value the name stays unknown here.
+  files.set(FILE_TYPE_PATH, "interface File { readonly __lecodesFile: true, readonly name: string, readonly size: number, readonly type: string }\n")
   // the server modules, and every other file of the project: the app's are read for the globals they use
   const roots = [...new Set([...Object.keys(modules).map(normalizePath).filter(p => files.has(p)), ...files.keys()])]
 
@@ -346,6 +351,7 @@ const lower = (ts: TS, checker: import("typescript").TypeChecker, type: import("
   }
   if (f & T.Union) return lowerMembers(ts, checker, (type as import("typescript").UnionType).types, where, stack)
   if (f & T.Intersection || f & T.Object) {
+    if (type.getProperty("__lecodesFile")) return { t: "file" }
     if (stack.has(type)) throw new Error(`${where}: recursive type ${checker.typeToString(type)}`)
     if (type.getCallSignatures().length || type.getConstructSignatures().length) throw new Error(`${where}: functions are not JSON`)
     stack.add(type)

package/src/inject.ts

@@ -44,6 +44,7 @@ export { Net, NetPlayer, Replicated, NetEntity, type NetMessage, type NetRole, t
 // only ever imports its server functions (docs/backend-plan.md §4).
 export { __rpc, __channel, __serverOnly, RpcError } from "./runtime/rpc"
 export type { ChannelSubscription } from "./server/channel"
+export type { StoredFile, StoredImage } from "./server/files/models"
 export { AudioPlayer, VideoPlayer } from "./runtime/media"
 // Game audio (docs/audio-plan.md): decoded clips, a voice pool, buses with effects; 3D through the
 // AudioSource / AudioZone aspects (gl/) and scene.audio.

package/src/runtime/rpc.ts

@@ -9,6 +9,8 @@
  *
  * Wire (implemented by the runner):
  *   POST <serverUrl>/api/<id>   body {"args":[…]}, `authorization: Bearer <session>` when known
+ *                               — with a `File` among the arguments: multipart, the field `args` is
+ *                               that JSON with `{"$file": <i>}` where the file stood, `file<i>` the files
  *   → 200 {"ok":true,"result":…,"session"?:"…"} | {"ok":false,"status":n,"message":"…","session"?:"…"}
  *   WS   <serverUrl>/ws  the channel socket — its frames are ./wire.ts
  *
@@ -17,7 +19,7 @@
  * User code never sees it — "am I logged in" is an endpoint (`me()`), see the plan.
  */
 
-import { fetch } from "./fetch"
+import { fetch, File, FormData } from "./fetch"
 import { localStorage } from "./storage"
 import { WebSocket } from "./net"
 import type { ChannelGroup, ClientFrame, ServerFrame } from "./wire"
@@ -64,12 +66,22 @@ export const __rpc = (serverUrl: string, id: string) => {
     // an optional argument left out is `undefined` in its place — JSON has no such value (it would
     // travel as null and fail the parameter's type), and it is the last ones
     while (args.length && args[args.length - 1] === undefined) args.pop()
-    const headers: Record<string, string> = { "content-type": "application/json" }
+    const headers: Record<string, string> = {}
     const session = getSession(serverUrl)
     if (session) headers.authorization = `Bearer ${session}`
+    // a File anywhere among the arguments leaves its place to a marker and travels beside them
+    const files: File[] = []
+    const json = JSON.stringify({ args }, (_key, value) => value instanceof File ? { $file: files.push(value) - 1 } : value)
+    let payload: string | FormData = json
+    if (files.length) {
+      const form = new FormData()
+      form.append("args", json)
+      files.forEach((file, i) => form.append(`file${i}`, file, file.name))
+      payload = form
+    } else headers["content-type"] = "application/json"
     let res
     try {
-      res = await fetch(`${serverUrl}/api/${encodeURIComponent(id)}`, { method: "POST", headers, body: JSON.stringify({ args }) })
+      res = await fetch(`${serverUrl}/api/${encodeURIComponent(id)}`, { method: "POST", headers, body: payload })
     } catch (e) {
       throw new RpcError(0, `Endpoint ${id}: request failed (${(e as Error)?.message ?? e})`)
     }

package/src/server/context.ts

@@ -15,6 +15,10 @@ export type RequestContext = {
   sessionToken?: string
   /** Set by the auth runtime after resolving the token — read via `db.auth`, not here. */
   auth?: unknown
+  /** The files a multipart call carried, as the receiving process left them (./files/host.ts `Upload`). */
+  uploads?: unknown[]
+  /** What `/files/<id>/<name>` is appended to in a stored file's url: the backend's own base, as this request reached it. */
+  filesBase?: string
 }
 
 type Provider = () => RequestContext | undefined

package/src/server/db/defineDb.ts

@@ -8,9 +8,11 @@
  * never sees a connection string.
  */
 
-import type { Field, FieldDef, ScalarKind } from "./fields"
+import { t, type Field, type FieldDef, type ScalarKind } from "./fields"
 import { createAuthApi } from "../auth/api"
 import { AUTH_IDENTITY_MODEL, AUTH_SESSION_MODEL, identityFields, sessionFields } from "../auth/models"
+import { createFileLayer } from "../files/db"
+import { FILE_MODEL, fileFields, fileOwnerKey, type FileField } from "../files/models"
 import { createQueryLayer, type FieldDesc, type MarciOp, type MarciTransport, type ModelsMeta } from "./marci/query"
 import type { AuthBinding, Db, Fields, Model, Schema, ValidateRefs } from "./types"
 
@@ -63,7 +65,12 @@ const buildMeta = (models: Record<string, Model>): Record<string, ModelMeta> =>
   for (const [name, m] of Object.entries(models)) {
     if (!/^[A-Z][A-Za-z0-9]*$/.test(name)) throw new Error(`defineDb: model name "${name}" must be PascalCase`)
     const fields: Record<string, FieldDef> = {}
-    for (const [key, f] of Object.entries(m.fields as Fields)) fields[key] = { ...(f as Field<any, any>).def }
+    for (const [key, f] of Object.entries(m.fields as Fields)) {
+      const def = (f as Field<any, any>).def
+      if (def.kind === "struct" && Object.values(def.fields!).some(inner => (inner as Field<any, any>).def.kind === "file"))
+        throw new Error(`defineDb: ${name}.${key} — a file belongs to a model's row: put the t.file() field on ${name} itself, not inside a struct`)
+      fields[key] = { ...def }
+    }
     if (fields.id && !fields.id.isId) fields.id.isId = true
     const idKeys = Object.keys(fields).filter(k => fields[k].isId)
     const uuidId = idKeys.length === 1 && idKeys[0] === "id" && fields.id.scalar === "uuid"
@@ -133,6 +140,7 @@ const emitField = (owner: string, key: string, d: FieldDef, extra: string[]): st
     case "one": type = d.model!; break
     case "many": type = `${d.model}[]`; attrs.push(`@bind(${d.model}.${d.back})`); break
     case "list": type = `${d.model}[]`; attrs.push("@list"); break
+    case "file": throw new Error(`${owner}.${key}: a file field is emitted as the relation it stands for`)
   }
   if (d.array && d.kind !== "many" && d.kind !== "list") type += "[]"
   if (d.optional) type += "?"
@@ -164,12 +172,14 @@ export const toMarci = (metas: Record<string, ModelMeta>): string => {
  * model — `key` / `body` scalars, `one` / `many` relations with their target. Structs are pseudo-models
  * (`User.info`) so an empty nested select fills with the struct's own scalars, as marcidb does.
  */
-const modelsMeta = (metas: Record<string, ModelMeta>): ModelsMeta => {
+const modelsMeta = (metas: Record<string, ModelMeta>, isFile: (model: string, key: string) => boolean): ModelsMeta => {
   const out: Record<string, FieldDesc[]> = {}
   const describe = (name: string, fields: Record<string, FieldDef>, implicitId: boolean) => {
     const descs: FieldDesc[] = implicitId ? [{ n: "id", k: "key" }] : []
     for (const [key, d] of Object.entries(fields)) {
-      if (isRel(d)) descs.push({ n: key, k: d.kind === "one" ? "one" : "many", m: d.model! })
+      // a file reads like a scalar: a query without a selection returns it (../files/db.ts makes it the relation select)
+      if (isFile(name, key)) descs.push({ n: key, k: "body" })
+      else if (isRel(d)) descs.push({ n: key, k: d.kind === "one" ? "one" : "many", m: d.model! })
       else if (d.kind === "struct") {
         const sub = `${name}.${key}`
         const inner: Record<string, FieldDef> = {}
@@ -204,21 +214,51 @@ export const defineDb = <const S extends Schema>(declared: S & ValidateRefs<S>,
   for (const name of [AUTH_SESSION_MODEL, AUTH_IDENTITY_MODEL]) {
     if (name in own) throw new Error(`defineDb: "${name}" is the platform's own model (it comes with .withAuth) — name yours differently`)
   }
+  if (FILE_MODEL in own) throw new Error(`defineDb: "${FILE_MODEL}" is the platform's own model (it comes with a t.file() field) — name yours differently`)
+  // the schema's file fields: each is, in the database, the reverse side of a reference on the platform's File
+  const fileList: FileField[] = []
+  for (const [name, m] of Object.entries(own)) {
+    for (const [key, f] of Object.entries(m.fields as Fields)) {
+      const def = (f as Field<any, any>).def
+      if (def.kind === "file") fileList.push({ model: name, key, array: def.array, owner: fileOwnerKey(name, key), ...(def.image ? { image: def.image } : {}) })
+    }
+  }
   // What is wrong with the project's own models is said HERE, at the definition, not at the first use:
   // checked against a stand-in for the one platform model they may point at.
   buildMeta({ ...own, [AUTH_SESSION_MODEL]: model({}) })
 
   let authModel: string | null = null
-  let sealed: { models: Record<string, Model>, schema: string, collections: Record<string, unknown>, auth: AuthBinding | null } | null = null
+  let sealed: { models: Record<string, Model>, schema: string, collections: Record<string, unknown>, auth: AuthBinding | null, files: FileField[] } | null = null
 
   const transport = () => {
     const t = options.transport ?? seam.__lecodesDbTransport
     if (!t) throw new Error("db: no transport — the host must call setDbTransport() before user code runs")
     return t
   }
+  // A db with file fields runs every operation through the file layer: a write of a file field is the
+  // row's operation and the ones on File after it, in one transaction.
+  let files: ReturnType<typeof createFileLayer> | null = null
+  const exec = async (op: MarciOp): Promise<any> => {
+    if (!files) return transport().exec(op)
+    const plan = await files.plan(op, 0)
+    if (!plan.after.length) return files.result(plan.op, await transport().exec(plan.op))
+    return (await transport().batch([plan.op, ...plan.after]))[0]
+  }
+  const batch = async (ops: MarciOp[]): Promise<any[]> => {
+    if (!files) return transport().batch(ops)
+    // the project's operations keep their places (its `ref`s count them); what follows them goes after
+    const plans: Awaited<ReturnType<typeof files.plan>>[] = []
+    for (let index = 0; index < ops.length; index++) plans.push(await files.plan(ops[index], index))
+    const results = await transport().batch([...plans.map(p => p.op), ...plans.flatMap(p => p.after)])
+    return plans.map((p, index) => files!.result(p.op, results[index]))
+  }
   const seal = () => {
     if (sealed) return sealed
     const models: Record<string, Model> = { ...own }
+    if (fileList.length) {
+      for (const f of fileList) models[f.model] = model({ ...(models[f.model].fields as Fields), [f.key]: t.many(FILE_MODEL, f.owner) })
+      models[FILE_MODEL] = model(fileFields(fileList))
+    }
     if (authModel) {
       models[AUTH_SESSION_MODEL] = model(sessionFields(authModel))
       models[AUTH_IDENTITY_MODEL] = model(identityFields(authModel))
@@ -246,10 +286,21 @@ export const defineDb = <const S extends Schema>(declared: S & ValidateRefs<S>,
       for (const [key, value] of missing) out[key] = [...value]
       return out
     }
+    const isFile = (name: string, key: string) => fileList.some(f => f.model === name && f.key === key)
+    const meta = modelsMeta(metas, isFile)
+    if (fileList.length) {
+      const relations: Record<string, Record<string, string>> = {}
+      const scalars: Record<string, string[]> = {}
+      for (const [name, descs] of Object.entries(meta)) {
+        relations[name] = Object.fromEntries(descs.filter(d => d.m).map(d => [d.n, d.m!]))
+        scalars[name] = descs.filter(d => d.k === "key" || d.k === "body").map(d => d.n)
+      }
+      files = createFileLayer(fileList, relations, scalars)
+    }
     // marcidb's own query builder over our metadata; the transport is the only host-specific piece
     const { collection } = createQueryLayer({
-      models: modelsMeta(metas),
-      run: op => transport().exec(op),
+      models: meta,
+      run: exec,
       // a single uuid key is generated client-side so `insert` needs no id (the .marci says @format(uuid))
       prepareInsert: (name, raw) => {
         const data = withDefaults(name, raw)
@@ -262,12 +313,13 @@ export const defineDb = <const S extends Schema>(declared: S & ValidateRefs<S>,
       models, schema: toMarci(metas), collections,
       // the platform's models are reached by role, never as `db.session` / `db.identity`
       auth: authModel ? { model: authModel, user: collection(authModel), session: collection(AUTH_SESSION_MODEL), identity: collection(AUTH_IDENTITY_MODEL) } : null,
+      files: fileList,
     }
     return sealed
   }
 
   const db: Record<string, unknown> = {
-    $transaction: async (ops: unknown[]) => { seal(); return transport().batch(ops.map(opOf)) },
+    $transaction: async (ops: unknown[]) => { seal(); return batch(ops.map(opOf)) },
     withAuth: ({ model: name }: { model: string }) => {
       if (sealed) throw new Error("defineDb(...).withAuth(): this db has already been used — sign-in is part of the definition, write it on defineDb(...) itself")
       if (authModel) throw new Error("defineDb(...).withAuth(): called twice on one db")
@@ -276,7 +328,7 @@ export const defineDb = <const S extends Schema>(declared: S & ValidateRefs<S>,
       for (const [key, f] of Object.entries(user.fields as Fields)) {
         const d = (f as Field<any, any>).def
         if (d.isId || key === "id") throw new Error(`defineDb(...).withAuth(): ${name} must keep the built-in id (it declares "${key}" as its key) — sessions and sign-in methods point at it`)
-        if (d.kind === "many" || d.kind === "list" || d.optional || d.hasDefault) continue
+        if (d.kind === "many" || d.kind === "list" || d.optional || d.hasDefault || (d.kind === "file" && d.array)) continue
         throw new Error(`defineDb(...).withAuth(): ${name}.${key} needs .optional() or .default(...) — the platform creates the row the first time someone signs in`)
       }
       authModel = name
@@ -288,6 +340,7 @@ export const defineDb = <const S extends Schema>(declared: S & ValidateRefs<S>,
     $schema: { get: () => seal().schema },
     $models: { get: () => seal().models },
     $auth: { get: () => seal().auth },
+    $files: { get: () => seal().files },
   })
   for (const name of Object.keys(own)) {
     Object.defineProperty(db, uncap(name), { enumerable: true, get: () => seal().collections[name] })

package/src/server/db/fields.ts

@@ -7,9 +7,10 @@
  */
 
 import type { JsonValue } from "./marci/query"
+import type { StoredFile, StoredImage } from "../files/models"
 
 export type ScalarKind = "string" | "int" | "float" | "bool" | "date" | "uuid" | ""
-export type FieldKind = "scalar" | "json" | "enum" | "struct" | "one" | "many" | "list"
+export type FieldKind = "scalar" | "json" | "enum" | "struct" | "one" | "many" | "list" | "file"
 export type OnDelete = "cascade" | "setNull" | "restrict"
 
 /** Phantom metadata — the type-level twin of `FieldDef`. */
@@ -48,6 +49,8 @@ export type FieldDef = {
   fields?: Record<string, Field<any, any>>
   /** one / many / list */
   model?: string
+  /** file: a picture (`t.image()`) — `max` is the most its longer side may be, px. */
+  image?: { max: number }
   /** many: the field on the related model that holds the reference (`@bind`); resolved by defineDb when omitted. */
   back?: string
 }
@@ -126,6 +129,23 @@ export const t = {
   /** Reverse side of a `t.one()` on `model` (the field is inferred when unambiguous). Read-only list. */
   many:   <N extends string>(model: N, backField?: string) =>
             create<never, Meta<{ kind: "many", model: N }>>(base("many", { model, back: backField })),
+  /**
+   * A stored file: written as a `File` (an upload — an endpoint's parameter), read as
+   * `{ url, name, type, size, width?, height? }`. `.optional()` = may be empty, `.array()` = an ordered
+   * list of files. It is deleted with its row — or when the field is given another file, or `null`.
+   */
+  file:   () => create<StoredFile, Meta<{ kind: "file" }>>(base("file")),
+  /**
+   * A stored PICTURE — a `t.file()` that takes images only and keeps them fit to show: turned the way
+   * the camera meant, without its metadata (a photo's place and time), as WebP, and no larger than
+   * `max` px on its longer side (2048 when not said; a picture is never enlarged).
+   * Read as a `StoredFile` whose `width` and `height` are always there. A GIF is kept as it is.
+   */
+  image:  (options: { max?: number } = {}) => {
+    const max = options.max ?? 2048
+    if (!Number.isInteger(max) || max < 1) throw new Error(`t.image({ max }): a whole number of pixels is expected, got ${max}`)
+    return create<StoredImage, Meta<{ kind: "file" }>>(base("file", { image: { max } }))
+  },
   /** Ordered relation list stored inline (`@list`) — hand-arranged collections, duplicates allowed. */
   list:   <N extends string>(model: N) => create<never, Meta<{ kind: "list", model: N }>>(base("list", { model })),
 }

package/src/server/db/httpTransport.ts

@@ -69,7 +69,7 @@ export const marciRequest = async (
 
 export const marciHttpTransport = (baseUrl: string, options: MarciHttpOptions = {}): MarciTransport => {
   const url = baseUrl.replace(/\/+$/, "")
-  const call = (path: string, body?: unknown) => marciRequest(`${url}/${path}`, { body, token: options.token, fetch: options.fetch })
+  const call = (path: string, body?: unknown, method?: string) => marciRequest(`${url}/${path}`, { body, method, token: options.token, fetch: options.fetch })
   return {
     exec(op: MarciOp) {
       switch (op.action) {
@@ -83,6 +83,14 @@ export const marciHttpTransport = (baseUrl: string, options: MarciHttpOptions =
         case "deleteMany": return call(`${op.model}/deleteMany`, op.query ?? {})
         case "count":      return call(`${op.model}/count`, op.query ?? {})
         case "aggregate":  return call(`${op.model}/aggregate`, op.query ?? {})
+        // a journal of the model's changes: create, read (`after` confirms), drop
+        case "$journalOpen": return call(`${op.model}/$journal/${op.journal!.name}`, { on: op.journal!.on })
+        case "$journalRead": {
+          const { name, after, limit, wait } = op.journal!
+          const params = [after !== undefined && `after=${after}`, limit !== undefined && `limit=${limit}`, wait && `wait=${wait}`].filter(Boolean).join("&")
+          return call(`${op.model}/$journal/${name}${params ? "?" + params : ""}`, undefined, "GET")
+        }
+        case "$journalDrop": return call(`${op.model}/$journal/${op.journal!.name}`, undefined, "DELETE")
         default: return Promise.reject(new Error(`marcidb: unknown action '${op.action}'`))
       }
     },

package/src/server/db/marci/query.ts

@@ -7,7 +7,7 @@
 // per-model type bags and MODELS metadata this file is parametrised by.
 //
 // Keep it dependency-free: besides shipping in `marcidb-client/runtime`, this file is vendored verbatim
-// into the lecodes SDK (`sdk/src/server/db/marci/query.ts`, `bun run sync:marcidb` there), which
+// into the lecodes SDK (`packages/sdk/src/server/db/marci/query.ts`, `bun run sync:marcidb` there), which
 // derives its model types from TS builders instead of codegen and plugs them into the same generics.
 
 // ───────────────────────────── query language types ─────────────────────────────
@@ -177,7 +177,9 @@ export type Op<T> = PromiseLike<T> & { readonly [__op]: T }
 
 // A transport-neutral operation descriptor and the pluggable transport that runs it. The HTTP transport
 // is selected by passing a URL string; marcidb-embedded provides an in-process FFI transport.
-export type MarciOp = { model: string, action: string, query?: any, data?: any, id?: any }
+export type MarciOp = { model: string, action: string, query?: any, data?: any, id?: any, journal?: JournalArgs }
+/** The arguments of a journal action (`$journalOpen` / `$journalRead` / `$journalDrop`). `wait` is in seconds. */
+export type JournalArgs = { name: string, on?: readonly JournalOp[], after?: number, limit?: number, wait?: number }
 export type MarciTransport = {
   exec(op: MarciOp): Promise<any>
   batch(ops: MarciOp[]): Promise<any[]>
@@ -275,8 +277,35 @@ export interface Query<T extends ModelTypes, Sel = T["scalars"]> extends Promise
   findFirst<Q extends T["query"] = {}>(query?: Q): Op<Rows<T, Q> | null>
 }
 
-/** `db.<model>`: the root query, plus `reindex()` for models with a `@custom` (vector / full-text) index. */
-export type Collection<T extends ModelTypes> = Query<T> & (T["reindex"] extends true ? { reindex(): Op<{ ok: boolean, indexed: number }> } : {})
+// ───────────────────────────── journals ─────────────────────────────
+
+/** What a journal can record. Only deletes so far. */
+export type JournalOp = "delete"
+/** One recorded change. `row` is the row as it last was: its id and every scalar field. */
+export type JournalEntry<T extends ModelTypes, O extends JournalOp = JournalOp> = { seq: number, op: O, row: Rows<T, T["scalars"]> }
+export type JournalOptions<O extends JournalOp> = {
+  /** The operations to record. A journal that exists with other ones is an error, not a redefinition. */
+  on: O | readonly O[]
+  /** `false`: the loop ends when the journal is read through. By default it waits for the next entry. */
+  wait?: boolean
+}
+/**
+ * A named, durable log of a model's changes. It starts recording when it is first asked for and keeps
+ * every entry until the loop that reads it has moved past it — an entry whose loop body threw, or that
+ * was never reached, is delivered again to the next reader of the same name.
+ */
+export interface Journal<T extends ModelTypes, O extends JournalOp = JournalOp> extends AsyncIterable<JournalEntry<T, O>> {
+  /** Drops the journal with whatever it still holds; the model's writes stop paying for it. */
+  drop(): Promise<void>
+}
+
+/**
+ * `db.<model>`: the root query, plus `reindex()` for models with a `@custom` (vector / full-text) index and
+ * `$journal(name, { on })` — the journal of this model's changes under that name, created on first use.
+ */
+export type Collection<T extends ModelTypes> = Query<T>
+  & (T["reindex"] extends true ? { reindex(): Op<{ ok: boolean, indexed: number }> } : {})
+  & { $journal<O extends JournalOp>(name: string, options: JournalOptions<O>): Journal<T, O> }
 
 // ───────────────────────────── builder runtime ─────────────────────────────
 
@@ -345,6 +374,43 @@ export function createQueryLayer(options: QueryLayerOptions): { op: (descriptor:
     return out;
   };
 
+  // `db.<model>.$journal(name, { on })`. The journal is opened at once — what happens between this call
+  // and the first read is already recorded. Reading confirms: each request carries the seq of the last
+  // entry the loop got past, which is what lets the engine drop it.
+  const journal = (model: string, name: string, options: { on: any; wait?: boolean }): any => {
+    const on = Array.isArray(options.on) ? options.on : [options.on];
+    const wait = options.wait === false ? 0 : 30;
+    const opened = run({ model, action: "$journalOpen", journal: { name, on } });
+    opened.catch(() => {}); // reported by the first read, not as an unhandled rejection
+    const read = (after: number | undefined, limit: number, wait: number): Promise<any[]> =>
+      run({ model, action: "$journalRead", journal: { name, after, limit, wait } });
+    return {
+      async *[Symbol.asyncIterator]() {
+        await opened;
+        let done: number | undefined;      // the last entry the loop body finished
+        let confirmed: number | undefined; // the last one a request has carried
+        try {
+          for (;;) {
+            const entries = await read(done, 100, wait);
+            confirmed = done;
+            if (entries.length === 0) {
+              if (wait === 0) return;
+              continue;
+            }
+            for (const entry of entries) {
+              yield entry;
+              done = entry.seq;
+            }
+          }
+        } finally {
+          // Left mid-batch (`break`, a throw): confirm what was finished, so it is not delivered again.
+          if (done !== undefined && done !== confirmed) await read(done, 1, 0).catch(() => {});
+        }
+      },
+      drop: () => opened.catch(() => {}).then(() => run({ model, action: "$journalDrop", journal: { name } })).then(() => {}),
+    };
+  };
+
   // `db.<model>` — an immutable builder; each clause returns a new one over the same `run`.
   const collection = (model: string): any => {
     const make = (st: QueryState): any => {
@@ -400,6 +466,7 @@ export function createQueryLayer(options: QueryLayerOptions): { op: (descriptor:
           return op({ model, action: "deleteMany", query: whereOnly() });
         },
         reindex: () => op({ model, action: "$reindex" }),
+        $journal: (name: string, options: { on: any; wait?: boolean }) => journal(model, name, options),
 
         findMany: (query?: Record<string, any>) => op({ model, action: "findMany", query: build(query) }),
         findFirst: (query?: Record<string, any>) => op({ model, action: "findFirst", query: build(query) }),

package/src/server/db/types.ts

@@ -9,6 +9,7 @@
 
 import type { Field, FieldMeta } from "./fields"
 import type { IdentityPublicFields, SessionPublicFields } from "../auth/models"
+import type { FileField, StoredFile, UploadedFile as File } from "../files/models"
 import type {
   CompareNumValue, CompareRefListValue, CompareRefValue, CompareStrValue, CompareValue, CustomSearchValue,
   FullTextSearch, JsonCondition, JsonPathWhere, Op, PrimitiveListUpdate, Query as MarciQuery, RefListUpdate,
@@ -49,13 +50,16 @@ type FieldRow<S, Fld, M extends FieldMeta = MetaOf<Fld>> =
   M["kind"] extends "one" ? Nullable<M, Row<S, ModelName<S, Fld>>>
   : M["kind"] extends "many" | "list" ? Row<S, ModelName<S, Fld>>[]
   : M["kind"] extends "struct" ? Nullable<M, StructRow<S, StructFieldsOf<Fld>>>
-  : Nullable<M, Arr<M, TsOf<Fld>>>
+  : Nullable<M, Arr<M, TsOf<Fld>>>            // a file too: `StoredFile`, `| null`, or a list
 
 /** Full row type of a model (relations included) — the `TModel` marcidb's `GetResult` selects from. */
 export type Row<S, N extends keyof S> = Id<S, N> & { [K in Exclude<keyof FieldsOf<S[N]>, IdKeys<FieldsOf<S[N]>>>]: FieldRow<S, FieldsOf<S[N]>[K]> }
 type StructRow<S, F extends Fields> = { [K in keyof F]: FieldRow<S, F[K]> }
 
-type ScalarKeys<F extends Fields> = { [K in keyof F]: MetaOf<F[K]>["kind"] extends "scalar" | "enum" | "json" ? K : never }[keyof F]
+/** What a query without a selection returns besides the id: the scalars, and the files. */
+type ScalarKeys<F extends Fields> = { [K in keyof F]: MetaOf<F[K]>["kind"] extends "scalar" | "enum" | "json" | "file" ? K : never }[keyof F]
+/** The fields a row is ordered and aggregated by. */
+type ValueKeys<F extends Fields> = { [K in keyof F]: MetaOf<F[K]>["kind"] extends "scalar" | "enum" | "json" ? K : never }[keyof F]
 type NumKeys<F extends Fields> = { [K in keyof F]: IsNum<MetaOf<F[K]>> extends true ? (MetaOf<F[K]>["array"] extends true ? never : K) : never }[keyof F]
 /** What an empty select returns: id + every scalar field. */
 export type Scalars<S, N extends keyof S> = Pick<Row<S, N>, (ScalarKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & keyof Row<S, N>>
@@ -68,6 +72,7 @@ type FieldInsert<S, Fld, M extends FieldMeta = MetaOf<Fld>> =
   M["kind"] extends "one" ? Nullable<M, Id<S, ModelName<S, Fld>>>
   : M["kind"] extends "many" | "list" ? Id<S, ModelName<S, Fld>>[]
   : M["kind"] extends "struct" ? Nullable<M, StructInsert<S, StructFieldsOf<Fld>>>
+  : M["kind"] extends "file" ? Nullable<M, Arr<M, File>>      // a new row takes uploads
   : Nullable<M, Arr<M, TsOf<Fld>>>
 
 type RequiredKeys<F extends Fields> = {
@@ -75,6 +80,7 @@ type RequiredKeys<F extends Fields> = {
     : MetaOf<F[K]>["optional"] extends true ? never
     : MetaOf<F[K]>["hasDefault"] extends true ? never
     : MetaOf<F[K]>["kind"] extends "many" | "list" ? never
+    : MetaOf<F[K]>["kind"] extends "file" ? (MetaOf<F[K]>["array"] extends true ? never : K)
     : K
 }[keyof F]
 type Simplify<T> = { [K in keyof T]: T[K] } & {}
@@ -92,6 +98,8 @@ type FieldUpdate<S, Fld, M extends FieldMeta = MetaOf<Fld>> =
   : M["kind"] extends "many" ? RefListUpdate<Id<S, ModelName<S, Fld>>>
   : M["kind"] extends "list" ? RefListUpdateOrdered<Id<S, ModelName<S, Fld>>>
   : M["kind"] extends "struct" ? RefUpdateStruct<StructInsert<S, StructFieldsOf<Fld>>, UpdateOf<S, StructFieldsOf<Fld>>> | null
+  // an upload replaces; the stored file the field holds, handed back, keeps it; null / a shorter list deletes
+  : M["kind"] extends "file" ? Nullable<M, Arr<M, File | StoredFile>>
   : M["array"] extends true ? TsOf<Fld>[] | PrimitiveListUpdate<TsOf<Fld>>
   : Nullable<M, TsOf<Fld> | (IsNum<M> extends true ? UpdateNumValue : never)>
 
@@ -120,6 +128,7 @@ type FieldWhere<S, Fld, M extends FieldMeta = MetaOf<Fld>> =
   : M["kind"] extends "many" | "list" ? CompareRefListValue<Where<S, ModelName<S, Fld>>>
   : M["kind"] extends "struct" ? CompareRefValue<WhereValue<StructWhereFields<S, StructFieldsOf<Fld>>> | null>
   : M["kind"] extends "json" ? JsonPathWhere | JsonCondition
+  : M["kind"] extends "file" ? never             // a row is not found by its file
   : M["array"] extends true ? TsOf<Fld>[]          // the whole array, equal — the engine has no filter by an item
   : ScalarWhere<TsOf<Fld>, M> | CustomSearchValue<FullTextSearch> | CustomSearchValue<VectorSearch>
 
@@ -128,7 +137,7 @@ type IdWhere<S, N extends keyof S> = { [K in keyof Id<S, N> as K extends keyof F
 export type Where<S, N extends keyof S> = WhereValue<WhereFieldsOf<S, FieldsOf<S[N]>> & IdWhere<S, N>>
 type StructWhereFields<S, F extends Fields> = WhereFieldsOf<S, F>
 
-type OrderKeys<S, N extends keyof S> = (ScalarKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & keyof Row<S, N>
+type OrderKeys<S, N extends keyof S> = (ValueKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & keyof Row<S, N>
 /** ONE field and its direction: the engine sorts by a single field, so a second key is a type error. */
 export type Order<S, N extends keyof S> = {
   [K in OrderKeys<S, N>]: { [P in K]: "asc" | "desc" } & { [P in Exclude<OrderKeys<S, N>, K>]?: never }
@@ -148,8 +157,8 @@ export type AggregateQuery<S, N extends keyof S> = {
   $count?: true
   $sum?: NumKeys<FieldsOf<S[N]>> & string
   $avg?: NumKeys<FieldsOf<S[N]>> & string
-  $min?: (ScalarKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & string
-  $max?: (ScalarKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & string
+  $min?: (ValueKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & string
+  $max?: (ValueKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & string
 }
 
 // ───────────────────────────── query / db ─────────────────────────────
@@ -197,6 +206,8 @@ type DbBase<S extends Schema> = {
   /** @internal */ readonly $models: Record<string, Model>
   /** @internal the collections sign-in works on; null = a db without `withAuth`. */
   readonly $auth: AuthBinding | null
+  /** @internal the schema's `t.file()` fields (../files/models.ts). */
+  readonly $files: FileField[]
 }
 
 export type Db<S extends Schema> = DbBase<S> & {