alepha 0.21.2 → 0.22.0

package/src/api/files/services/FileService.ts

@@ -11,10 +11,11 @@ import {
   type DurationLike,
 } from "alepha/datetime";
 import { $logger } from "alepha/logger";
-import { $repository, type Page } from "alepha/orm";
+import { $repository, type Page, RepositoryProvider } from "alepha/orm";
 import type { UserAccountToken } from "alepha/security";
 import type { Ok } from "alepha/server";
 import { NotFoundError } from "alepha/server";
+import { FileSystemProvider } from "alepha/system";
 import { type FileEntity, files } from "../entities/files.ts";
 import type { FileQuery } from "../schemas/fileQuerySchema.ts";
 import type { FileResource } from "../schemas/fileResourceSchema.ts";
@@ -24,9 +25,39 @@ export class FileService {
   protected readonly alepha = $inject(Alepha);
   protected readonly log = $logger();
   protected readonly dateTimeProvider = $inject(DateTimeProvider);
+  protected readonly repositoryProvider = $inject(RepositoryProvider);
+  protected readonly fileSystem = $inject(FileSystemProvider);
   protected readonly defaultBucket = $bucket({ name: "default" });
   public readonly fileRepository = $repository(files);
 
+  /**
+   * Best-effort left join embedding the uploader on every file row, so the
+   * admin UI can render `user.email` instead of the bare `creator` UUID.
+   * Joins `files.creator` → `users.id`. Only applied when the `users` table is
+   * actually registered in the app (see `findFiles`) — the files module stays
+   * usable standalone, without `alepha/api/users`. Targets the default `users`
+   * table, so creators in non-default realms come back unmatched (`user`
+   * undefined), which the UI handles by falling back to `creatorName`.
+   *
+   * The `users` entity is resolved from the repository registry at runtime
+   * rather than imported: the users module already depends on the files module
+   * (avatars), so a compile-time import here would form a circular dependency.
+   */
+  protected resolveCreatorJoin() {
+    const usersEntity = this.repositoryProvider
+      .getRepositories()
+      .find((repo) => repo.entity.name === "users")?.entity;
+    if (!usersEntity) {
+      return undefined;
+    }
+    return {
+      user: {
+        join: usersEntity,
+        on: ["creator", usersEntity.cols.id] as ["creator", { name: string }],
+      },
+    };
+  }
+
   protected onUploadFile = $hook({
     on: "bucket:file:uploaded",
     handler: async ({ file, bucket, options, id }) => {
@@ -36,18 +67,20 @@ export class FileService {
 
       const checksum = await this.calculateChecksum(file);
 
-      await this.fileRepository.create({
-        blobId: id,
-        mimeType: file.type,
-        name: file.name,
-        originalName: file.name,
-        size: file.size,
-        creator: options.user?.id,
-        creatorRealm: options.user?.realm,
-        expirationDate: this.getExpirationDate(options.ttl),
-        bucket: bucket.name,
-        checksum,
-      });
+      await this.persistBlobMetadata(bucket, id, () =>
+        this.fileRepository.create({
+          blobId: id,
+          mimeType: file.type,
+          name: file.name,
+          originalName: file.name,
+          size: file.size,
+          creator: options.user?.id,
+          creatorRealm: options.user?.realm,
+          expirationDate: this.getExpirationDate(options.ttl),
+          bucket: bucket.name,
+          checksum,
+        }),
+      );
     },
   });
 
@@ -66,15 +99,28 @@ export class FileService {
   /**
    * Calculates SHA-256 checksum of a file.
    *
+   * Reads the whole file into memory. Callers that already hold the bytes
+   * should use {@link hashBuffer} instead to avoid re-reading — re-reading a
+   * one-shot stream either yields the wrong hash or drains a stream another
+   * step still needs.
+   *
    * @param file - The file to calculate checksum for
    * @returns Hexadecimal string representation of the SHA-256 hash
    * @protected
    */
   protected async calculateChecksum(file: FileLike): Promise<string> {
-    const buffer = await file.arrayBuffer();
-    const hash = createHash("sha256");
-    hash.update(Buffer.from(buffer));
-    return hash.digest("hex");
+    return this.hashBuffer(await file.arrayBuffer());
+  }
+
+  /**
+   * Calculates the SHA-256 checksum of an already-read body.
+   *
+   * @param data - The file bytes
+   * @returns Hexadecimal string representation of the SHA-256 hash
+   * @protected
+   */
+  protected hashBuffer(data: ArrayBuffer): string {
+    return createHash("sha256").update(Buffer.from(data)).digest("hex");
   }
 
   /**
@@ -141,8 +187,17 @@ export class FileService {
       where.createdAt = { lte: q.createdBefore };
     }
 
+    // The creator join requires the `users` table. Only opt in when a users
+    // repository is registered (i.e. `alepha/api/users` is loaded) so the
+    // files module — and its standalone tests — keep working without it.
+    const withCreator = this.resolveCreatorJoin();
+
     return await this.fileRepository
-      .paginate(q, { where }, { count: true })
+      .paginate(
+        q,
+        { where, ...(withCreator ? { with: withCreator } : {}) },
+        { count: true },
+      )
       .then((page) => {
         return {
           ...page,
@@ -206,7 +261,20 @@ export class FileService {
   ): Promise<FileEntity> {
     const bucket = this.bucket(options.bucket);
 
-    const checksum = await this.calculateChecksum(file);
+    // Read the source exactly once. The checksum and the stored bytes are
+    // both derived from this single buffer, so a one-shot stream is never
+    // read twice — the previous code checksummed the file and then let
+    // bucket.upload read it again, which drained the stream and stored an
+    // empty blob. Uploads are size-capped (bucket maxSize / multipart
+    // limits), so buffering here is intentional and bounded.
+    const data = await file.arrayBuffer();
+    const checksum = this.hashBuffer(data);
+    file = this.fileSystem.createFile({
+      arrayBuffer: data,
+      name: file.name,
+      type: file.type,
+    });
+
     const blobId = await bucket.upload(file, { persist: false });
 
     let expirationDate: string | undefined;
@@ -218,20 +286,58 @@ export class FileService {
       expirationDate = this.getExpirationDate(bucket.options.ttl);
     }
 
-    return await this.fileRepository.create({
-      blobId: blobId,
-      mimeType: file.type,
-      name: file.name,
-      originalName: file.name,
-      size: file.size,
-      creator: options.user?.id,
-      creatorRealm: options.user?.realm,
-      creatorName: options.user?.name,
-      expirationDate,
-      bucket: bucket.name,
-      tags: options.tags,
-      checksum,
-    });
+    return await this.persistBlobMetadata(bucket, blobId, () =>
+      this.fileRepository.create({
+        blobId: blobId,
+        mimeType: file.type,
+        name: file.name,
+        originalName: file.name,
+        size: file.size,
+        creator: options.user?.id,
+        creatorRealm: options.user?.realm,
+        creatorName: options.user?.name,
+        expirationDate,
+        bucket: bucket.name,
+        tags: options.tags,
+        checksum,
+      }),
+    );
+  }
+
+  /**
+   * Persists the metadata row for an already-uploaded blob, deleting the
+   * blob if the insert fails. Uploads are not atomic: the blob is written to
+   * storage first (the row needs the returned `blobId`), so a failed insert
+   * would otherwise leak the blob — an orphaned blob with no DB row. This
+   * compensates by removing the blob, favouring the recoverable failure
+   * (a missing blob) over the worse one (a row pointing at nothing).
+   *
+   * Best-effort: cleanup runs with `skipHook` so it neither re-emits
+   * `bucket:file:deleted` nor touches the (non-existent) DB row, and a failed
+   * cleanup is logged rather than thrown. The original write error is always
+   * rethrown so callers still see the real failure.
+   *
+   * @param bucket - The bucket the blob was uploaded to
+   * @param blobId - The id returned by `bucket.upload`
+   * @param insert - Thunk performing the metadata insert
+   * @returns The created file entity
+   */
+  protected async persistBlobMetadata(
+    bucket: BucketPrimitive,
+    blobId: string,
+    insert: () => Promise<FileEntity>,
+  ): Promise<FileEntity> {
+    try {
+      return await insert();
+    } catch (error) {
+      await bucket.delete(blobId, true).catch((cleanupError) => {
+        this.log.warn(
+          `Failed to remove orphaned blob ${blobId} from bucket ${bucket.name} after a metadata write failure`,
+          cleanupError,
+        );
+      });
+      throw error;
+    }
   }
 
   /**
@@ -388,50 +494,42 @@ export class FileService {
   /**
    * Gets storage statistics including total size, file count, and breakdowns by bucket and MIME type.
    *
+   * Aggregated in SQL (`SUM`/`COUNT` + `GROUP BY`) rather than by loading
+   * every row into memory — the table can hold millions of files, and this
+   * endpoint must stay O(groups), not O(rows). Totals are derived from the
+   * per-bucket groups (every row has exactly one bucket), so no extra query
+   * is needed.
+   *
    * @returns Storage statistics with aggregated data
    */
   public async getStorageStats(): Promise<StorageStats> {
-    const allFiles = await this.fileRepository.findMany({});
-
-    const totalSize = allFiles.reduce((sum, file) => sum + file.size, 0);
-    const totalFiles = allFiles.length;
-
-    // Group by bucket
-    const bucketMap = new Map<
-      string,
-      { totalSize: number; fileCount: number }
-    >();
-    for (const file of allFiles) {
-      const existing = bucketMap.get(file.bucket) || {
-        totalSize: 0,
-        fileCount: 0,
-      };
-      existing.totalSize += file.size;
-      existing.fileCount += 1;
-      bucketMap.set(file.bucket, existing);
-    }
-
-    // Group by MIME type
-    const mimeTypeMap = new Map<string, number>();
-    for (const file of allFiles) {
-      const existing = mimeTypeMap.get(file.mimeType) || 0;
-      mimeTypeMap.set(file.mimeType, existing + 1);
-    }
+    const [byBucketRows, byMimeTypeRows] = await Promise.all([
+      this.fileRepository.aggregate({
+        select: { bucket: true, size: { sum: true, count: true } },
+        groupBy: ["bucket"],
+      }),
+      this.fileRepository.aggregate({
+        select: { mimeType: true, size: { count: true } },
+        groupBy: ["mimeType"],
+      }),
+    ]);
+
+    const byBucket = byBucketRows.map((row) => ({
+      bucket: row.bucket,
+      totalSize: row.size.sum,
+      fileCount: row.size.count,
+    }));
+
+    const byMimeType = byMimeTypeRows.map((row) => ({
+      mimeType: row.mimeType,
+      fileCount: row.size.count,
+    }));
 
     return {
-      totalSize,
-      totalFiles,
-      byBucket: Array.from(bucketMap.entries()).map(([bucket, stats]) => ({
-        bucket,
-        totalSize: stats.totalSize,
-        fileCount: stats.fileCount,
-      })),
-      byMimeType: Array.from(mimeTypeMap.entries()).map(
-        ([mimeType, fileCount]) => ({
-          mimeType,
-          fileCount,
-        }),
-      ),
+      totalSize: byBucket.reduce((sum, b) => sum + b.totalSize, 0),
+      totalFiles: byBucket.reduce((sum, b) => sum + b.fileCount, 0),
+      byBucket,
+      byMimeType,
     };
   }
 

package/src/api/jobs/__tests__/$job.spec.ts

@@ -71,7 +71,7 @@ describe("$job — registration validation", () => {
 // ---------------------------------------------------------------------------
 
 describe("$job — cron mode", () => {
-  it("runs handler inline on trigger, no DB row on success by default", async ({
+  it("runs handler inline on trigger and keeps the last successful run", async ({
     expect,
   }) => {
     const alepha = makeApp();
@@ -89,6 +89,29 @@ describe("$job — cron mode", () => {
     await alepha.start();
     await app.tick.trigger();
     expect(calls).toBe(1);
+    // Cron jobs keep their last successful run by default so "Last run" works.
+    const rows = await app.executions.findMany({
+      where: { jobName: { eq: "App.tick" } },
+    });
+    expect(rows).toHaveLength(1);
+    expect(rows[0].status).toBe("ok");
+  });
+
+  it("records no row on success when record is 'error' (opt-out)", async ({
+    expect,
+  }) => {
+    const alepha = makeApp();
+    class App {
+      executions = $repository(jobExecutionEntity);
+      tick = $job({
+        cron: "0 0 * * *",
+        record: "error",
+        handler: async () => {},
+      });
+    }
+    const app = alepha.inject(App);
+    await alepha.start();
+    await app.tick.trigger();
     const rows = await app.executions.findMany({
       where: { jobName: { eq: "App.tick" } },
     });

package/src/api/jobs/index.ts

@@ -1,4 +1,5 @@
 import { $module } from "alepha";
+import { AlephaBackground } from "alepha/background";
 import type { DateTime } from "alepha/datetime";
 import { AlephaLock } from "alepha/lock";
 import { AlephaQueue } from "alepha/queue";
@@ -62,8 +63,8 @@ declare module "alepha" {
  *   is overkill.
  *
  * **Retries** are sweep-driven across all modes (no exponential backoff).
- * Granularity is bounded by `sweepCron` (default 5 min). The first retry
- * may land anywhere from a few seconds to ~5 min later depending on when
+ * Granularity is bounded by `sweepCron` (default 15 min). The first retry
+ * may land anywhere from a few seconds to ~15 min later depending on when
  * the next sweep tick fires. Cron jobs that declare `retry` go through
  * the same sweep path — a transient failure no longer means waiting for
  * the next cron tick (useful for once-daily jobs).
@@ -86,7 +87,7 @@ declare module "alepha" {
 export const AlephaApiJobs = $module({
   name: "alepha.api.jobs",
   primitives: [$job],
-  imports: [AlephaScheduler, AlephaLock],
+  imports: [AlephaScheduler, AlephaLock, AlephaBackground],
   services: [JobProvider, JobService, AdminJobController, DirectJobDispatcher],
 });
 

package/src/api/jobs/primitives/$job.ts

@@ -77,8 +77,8 @@ export interface JobPrimitiveOptions<T extends TSchema = TSchema>
    * Cron-mode jobs do not retry — the next tick re-runs.
    *
    * Retries are picked up by the reconciliation sweep, so retry granularity
-   * is bounded by `sweepCron` (default 5 minutes). The first retry may run
-   * earlier than 5 minutes if the sweep tick happens sooner.
+   * is bounded by `sweepCron` (default 15 minutes). The first retry may run
+   * earlier than 15 minutes if the sweep tick happens sooner.
    */
   retry?: JobRetryOptions;
 
@@ -115,10 +115,14 @@ export interface JobPrimitiveOptions<T extends TSchema = TSchema>
   /**
    * Whether to record successful executions.
    *
-   * - `"error"` (default for cron, default for queue): only error/cancelled rows kept
+   * - `"error"` (default for queue): only error/cancelled rows kept
    * - `"all"`: keep success rows too (bounded by `keepLastSuccess`)
    * - `"none"`: fire-and-forget, no row even on error
    *
+   * **Cron jobs default to keeping their last successful run** (`record: "all"`
+   * with `keep.ok = 1`) so the admin "Last run" is accurate — set
+   * `record: "error"` to opt out (e.g. for very high-frequency crons).
+   *
    * Note: queue-mode jobs always write a `pending` row at push time (outbox).
    * This setting controls whether that row is kept on success.
    */

package/src/api/jobs/providers/DirectJobDispatcher.ts

@@ -1,4 +1,5 @@
 import { $inject, Alepha } from "alepha";
+import { BackgroundTaskProvider } from "alepha/background";
 import { $logger } from "alepha/logger";
 import { JobDispatcher } from "./JobDispatcher.ts";
 import { JobProvider } from "./JobProvider.ts";
@@ -12,20 +13,17 @@ import { JobProvider } from "./JobProvider.ts";
  * if the process dies before the handler finishes, the next sweep tick
  * picks the row up and re-dispatches.
  *
- * **Cloudflare Workers** — when an `executionCtx.waitUntil` is available
- * in the alepha store at `cloudflare.waitUntil`, the dispatch wraps the
- * background promise with `waitUntil` so the runtime keeps the isolate
- * alive past the HTTP response. Without this, the handler would be
- * terminated when the response is returned and only the next sweep
- * (every 5 min by default) would re-dispatch.
- *
- * **Vercel / single-Node** — on long-running runtimes the event loop
- * keeps the promise alive naturally; no special wiring is required.
+ * Keeping the isolate alive past the HTTP response (Cloudflare Workers) vs.
+ * relying on the event loop (Node/Vercel) is delegated to
+ * {@link BackgroundTaskProvider.defer} — this dispatcher stays
+ * platform-agnostic. The DB outbox row remains the durability guarantee: if
+ * the process dies mid-handler, the next sweep re-dispatches.
  */
 export class DirectJobDispatcher extends JobDispatcher {
   public readonly kind = "direct" as const;
 
   protected readonly alepha = $inject(Alepha);
+  protected readonly background = $inject(BackgroundTaskProvider);
   protected readonly log = $logger();
 
   // Lazy: resolved on first dispatch to break the JobProvider ↔ Dispatcher
@@ -40,32 +38,15 @@ export class DirectJobDispatcher extends JobDispatcher {
   }
 
   public async dispatch(jobName: string, executionId: string): Promise<void> {
-    const promise = this.getJobProvider()
-      .processExecution(jobName, executionId)
-      .catch((err) => {
-        this.log.warn(
-          `Direct execution failed for '${jobName}' (sweep will retry)`,
-          err,
-        );
-      });
-
-    // Cloudflare Workers: keep the isolate alive past the HTTP response so
-    // the handler actually finishes. Outside CF this read returns undefined
-    // and we fall through to plain fire-and-track.
-    const waitUntil = this.alepha.store.get("cloudflare.waitUntil") as
-      | ((p: Promise<unknown>) => void)
-      | undefined;
-    if (typeof waitUntil === "function") {
-      try {
-        waitUntil(promise);
-      } catch (e) {
-        // The runtime may reject waitUntil if called outside a request scope.
-        // Promise still runs; just log.
-        this.log.debug(
-          "waitUntil rejected — falling back to fire-and-track",
-          e,
-        );
-      }
-    }
+    this.background.defer(() =>
+      this.getJobProvider()
+        .processExecution(jobName, executionId)
+        .catch((err) => {
+          this.log.warn(
+            `Direct execution failed for '${jobName}' (sweep will retry)`,
+            err,
+          );
+        }),
+    );
   }
 }

package/src/api/jobs/providers/JobProvider.ts

@@ -152,6 +152,38 @@ export class JobProvider {
   protected readonly perExecutionLogs = new Map<string, LogEntry[]>();
   protected stopping = false;
 
+  constructor() {
+    // Register the sweep + trim crons eagerly so the wrangler build
+    // step (which reads `CronProvider.getCronJobs()` without running
+    // any lifecycle hooks) sees them and emits the matching cron
+    // triggers into wrangler.jsonc. CronProvider's `start` hook will
+    // boot whatever is in `cronJobs` at runtime — registering here
+    // (constructor, runs at inject time) is equivalent to registering
+    // in `onStart` from CronProvider's POV but visible to build-time
+    // introspection.
+    this.cronProvider.createCronJob(
+      "api:jobs:sweep",
+      this.config.sweepCron,
+      async () => {
+        await this.sweep();
+      },
+      true,
+    );
+    this.cronProvider.createCronJob(
+      "api:jobs:trim",
+      this.config.trimCron,
+      async () => {
+        if (this.stopping) return;
+        try {
+          await this.trimRingBuffers();
+        } catch (e) {
+          this.log.error("Trim failed", { error: e });
+        }
+      },
+      true,
+    );
+  }
+
   // --- Registration -----------------------------------------------------------------------------------------------
 
   public registerJob(name: string, options: JobPrimitiveOptions): void {
@@ -170,6 +202,21 @@ export class JobProvider {
     }
 
     const kind: "cron" | "queue" = options.cron ? "cron" : "queue";
+
+    // Cron jobs keep their last successful run by default, so the admin
+    // "Last run" reflects reality — a routine cron success is otherwise
+    // unrecorded (only failures are), making every healthy cron look like it
+    // "never" ran. Bounded to the latest row (keep.ok=1) to avoid unbounded
+    // growth from recurring ticks. Opt out of recording successes entirely
+    // with `record: "error"` (recommended for very high-frequency crons).
+    if (kind === "cron" && options.record === undefined) {
+      options = {
+        ...options,
+        record: "all",
+        keep: { ...options.keep, ok: options.keep?.ok ?? 1 },
+      };
+    }
+
     this.jobs.set(name, { name, options, kind });
     this.log.debug(`Registered ${kind} job '${name}'`, {
       cron: options.cron,
@@ -996,8 +1043,8 @@ export class JobProvider {
     if (canRetry) {
       // Retries are sweep-driven: write the row as `scheduled` with
       // `scheduledAt = now`. The next sweep tick (every `sweepCron`,
-      // default 5 minutes) re-dispatches it. This means the first retry
-      // can land anywhere from a few seconds to ~5 minutes later — the
+      // default 15 minutes) re-dispatches it. This means the first retry
+      // can land anywhere from a few seconds to ~15 minutes later — the
       // exact moment depends on when the next sweep tick fires.
       //
       // We deliberately do NOT use exponential backoff or a local timer.
@@ -1246,28 +1293,10 @@ export class JobProvider {
         await this.sweep();
       }
 
-      this.cronProvider.createCronJob(
-        "api:jobs:sweep",
-        this.config.sweepCron,
-        async () => {
-          await this.sweep();
-        },
-        true,
-      );
-
-      this.cronProvider.createCronJob(
-        "api:jobs:trim",
-        this.config.trimCron,
-        async () => {
-          if (this.stopping) return;
-          try {
-            await this.trimRingBuffers();
-          } catch (e) {
-            this.log.error("Trim failed", { error: e });
-          }
-        },
-        true,
-      );
+      // Sweep + trim cron registrations live in the constructor — see
+      // the note there. CronProvider's `start` hook (which runs before
+      // ours via DI order) has already booted them by the time we get
+      // here.
     },
   });
 

package/src/api/jobs/schemas/jobConfigAtom.ts

@@ -34,7 +34,7 @@ export const jobConfig = $atom({
     }),
   }),
   default: {
-    sweepCron: "*/5 * * * *",
+    sweepCron: "*/15 * * * *",
     trimCron: "0 * * * *",
     staleThreshold: 300_000,
     runTimeout: 1_800_000,

package/src/api/jobs/schemas/jobExecutionResourceSchema.ts

@@ -12,7 +12,10 @@ import { jobExecutionEntity } from "../entities/jobExecutionEntity.ts";
  * - `can` derives the available admin actions from the row's status.
  */
 export const jobExecutionResourceSchema = t.extend(
-  jobExecutionEntity.schema,
+  // `t.extend` composes (interface-extends), it does not override: the base
+  // `priority` (integer) would still be enforced alongside the enum below and
+  // reject the int→string transform. Drop it from the base first.
+  t.omit(jobExecutionEntity.schema, ["priority"]),
   {
     priority: t.enum(["critical", "high", "normal", "low"]),
     can: t.object({

package/src/api/keys/schemas/adminApiKeyResourceSchema.ts

@@ -1,4 +1,4 @@
-import { t } from "alepha";
+import { type Static, t } from "alepha";
 
 export const adminApiKeyResourceSchema = t.object({
   id: t.uuid(),
@@ -15,3 +15,5 @@ export const adminApiKeyResourceSchema = t.object({
   revokedAt: t.optional(t.datetime()),
   usageCount: t.integer(),
 });
+
+export type AdminApiKeyResource = Static<typeof adminApiKeyResourceSchema>;

package/src/api/parameters/__tests__/$parameter.spec.ts

@@ -1321,7 +1321,7 @@ describe("getCurrentWithDefault", () => {
     expect(result.schema).toBeNull();
   });
 
-  it("should return default when primitive registered but no DB value", async () => {
+  it("should lazy-seed v1 from defaults when primitive registered but no DB value", async () => {
     class AppConfig {
       features = $parameter({
         name: "gwd.default.only",
@@ -1338,7 +1338,19 @@ describe("getCurrentWithDefault", () => {
     const provider = alepha.inject(ParameterProvider);
     const result = await provider.getCurrentWithDefault("gwd.default.only");
 
-    expect(result.current).toBeNull();
+    // Auto-seed: getCurrentWithDefault materializes v1 from the compiled
+    // defaults when nothing is in the DB yet, so the admin UI always has a
+    // concrete current row to edit / roll back / compare against.
+    expect(result.current).not.toBeNull();
+    expect(result.current!.version).toBe(1);
+    expect(result.current!.status).toBe("current");
+    expect(result.current!.content).toEqual({
+      enableBeta: false,
+      maxUploadSize: 10485760,
+    });
+    expect(result.current!.changeDescription).toBe(
+      "Auto-seeded from compiled defaults",
+    );
     expect(result.next).toBeNull();
     expect(result.defaultValue).toEqual({
       enableBeta: false,
@@ -1349,6 +1361,11 @@ describe("getCurrentWithDefault", () => {
       maxUploadSize: 10485760,
     });
     expect(result.schema).not.toBeNull();
+
+    // Idempotent: a second call returns the same row without re-creating.
+    const second = await provider.getCurrentWithDefault("gwd.default.only");
+    expect(second.current!.id).toBe(result.current!.id);
+    expect(second.current!.version).toBe(1);
   });
 
   it("should return current, next, and defaults when all exist", async () => {