@hiai-gg/docsmint 0.3.5 → 0.3.7

package/dist/backend/index.js

@@ -42744,6 +42744,7 @@ __export(exports_schema, {
   documentPipelineBatches: () => documentPipelineBatches,
   documentEmbeddings: () => documentEmbeddings,
   documentEmbeddingRelations: () => documentEmbeddingRelations,
+  documentCreateOperations: () => documentCreateOperations,
   categoryRelations: () => categoryRelations,
   categories: () => categories,
   auditLog: () => auditLog,
@@ -42753,7 +42754,7 @@ __export(exports_schema, {
   apiKeyRelations: () => apiKeyRelations,
   accounts: () => accounts
 });
-var vector4, tsvector, documentVisibilityEnum, shareRoleEnum, embeddingStatusEnum, pipelineStageEnum, pipelineStatusEnum, lifecycleOperationKindEnum, lifecycleOperationStatusEnum, users, sessions, accounts, verifications, folders, folderRelations, documents, documentRelations, documentPipelineRuns, documentPipelineBatches, tags, tagRelations, categories, categoryRelations, documentTags, documentTagRelations, shareLinks, shareLinkRelations, guestAccess, guestAccessRelations, attachments, attachmentRelations, versions, documentEmbeddings, documentEmbeddingRelations, apiKeys, apiKeyRelations, auditLog, lifecycleOperations, versionRelations;
+var vector4, tsvector, documentVisibilityEnum, shareRoleEnum, embeddingStatusEnum, pipelineStageEnum, pipelineStatusEnum, lifecycleOperationKindEnum, lifecycleOperationStatusEnum, users, sessions, accounts, verifications, folders, folderRelations, documents, documentRelations, documentPipelineRuns, documentPipelineBatches, tags, tagRelations, categories, categoryRelations, documentTags, documentTagRelations, shareLinks, shareLinkRelations, guestAccess, guestAccessRelations, attachments, attachmentRelations, versions, documentEmbeddings, documentEmbeddingRelations, apiKeys, apiKeyRelations, auditLog, lifecycleOperations, documentCreateOperations, versionRelations;
 var init_schema2 = __esm(() => {
   init_pg_core();
   init_drizzle_orm();
@@ -43209,7 +43210,8 @@ var init_schema2 = __esm(() => {
   ]);
   lifecycleOperations = pgTable("lifecycle_operations", {
     id: uuid("id").primaryKey().defaultRandom(),
-    actorUserId: uuid("actor_user_id").notNull().references(() => users.id, { onDelete: "restrict" }),
+    actorUserId: uuid("actor_user_id").references(() => users.id, { onDelete: "set null" }),
+    actorSubjectHash: text("actor_subject_hash").notNull(),
     idempotencyKey: text("idempotency_key").notNull(),
     operationKind: lifecycleOperationKindEnum("operation_kind").notNull(),
     status: lifecycleOperationStatusEnum("status").notNull().default("pending"),
@@ -43227,7 +43229,19 @@ var init_schema2 = __esm(() => {
     uniqueIndex("lifecycle_operations_actor_idempotency_idx").on(table3.actorUserId, table3.idempotencyKey),
     index("lifecycle_operations_status_lease_idx").on(table3.status, table3.leaseExpiresAt),
     index("lifecycle_operations_actor_idx").on(table3.actorUserId),
-    index("lifecycle_operations_retryable_idx").on(table3.status).where(sql`${table3.status} = 'retryable'`)
+    index("lifecycle_operations_retryable_idx").on(table3.status).where(sql`${table3.status} = 'retryable'`),
+    check2("lifecycle_operations_actor_subject_hash", sql`${table3.actorSubjectHash} ~ '^[a-f0-9]{64}$'`)
+  ]);
+  documentCreateOperations = pgTable("document_create_operations", {
+    id: uuid("id").primaryKey().defaultRandom(),
+    workspaceId: text("workspace_id").notNull(),
+    actorUserId: uuid("actor_user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+    idempotencyKey: text("idempotency_key").notNull(),
+    documentId: uuid("document_id").notNull().references(() => documents.id, { onDelete: "cascade" }),
+    createdAt: timestamp("created_at").defaultNow().notNull()
+  }, (table3) => [
+    uniqueIndex("document_create_operations_workspace_actor_key_idx").on(table3.workspaceId, table3.actorUserId, table3.idempotencyKey),
+    uniqueIndex("document_create_operations_document_idx").on(table3.documentId)
   ]);
   versionRelations = relations(versions, ({ one }) => ({
     document: one(documents, {
@@ -198271,7 +198285,8 @@ init_config();
 var DOCSMINT_WORKSPACE_CONTEXT_HEADER = "x-docsmint-workspace-context";
 var EXTERNAL_TENANT_CONTEXT_HEADER = "x-hiai-tenant-context";
 var WORKSPACE_CONTEXT_MAX_LENGTH = 128;
-var WORKSPACE_CONTEXT_MAX_TTL_SECONDS = 300;
+var WORKSPACE_CONTEXT_MAX_TTL_SECONDS = 60;
+var WORKSPACE_CONTEXT_CLOCK_SKEW_SECONDS = 5;
 
 class ExternalTenantContextError extends Error {
   status = 401;
@@ -198334,14 +198349,14 @@ async function verifyExternalTenantAssertion(assertion, options) {
   if (decoded.issuer !== options.issuer)
     throw new Error("Invalid tenant assertion issuer");
   const now2 = options.nowSeconds ?? Math.floor(Date.now() / 1000);
-  const skew = options.clockSkewSeconds ?? 5;
+  const skew = Math.min(options.clockSkewSeconds ?? WORKSPACE_CONTEXT_CLOCK_SKEW_SECONDS, WORKSPACE_CONTEXT_CLOCK_SKEW_SECONDS);
   if (decoded.issuedAt > now2 + skew)
     throw new Error("Tenant assertion is not yet valid");
   if (decoded.expiresAt <= now2 - skew)
     throw new Error("Tenant assertion is expired");
   if (decoded.expiresAt <= decoded.issuedAt)
     throw new Error("Invalid tenant assertion lifetime");
-  if (decoded.expiresAt - decoded.issuedAt > (options.maxTtlSeconds ?? WORKSPACE_CONTEXT_MAX_TTL_SECONDS))
+  if (decoded.expiresAt - decoded.issuedAt > Math.min(options.maxTtlSeconds ?? WORKSPACE_CONTEXT_MAX_TTL_SECONDS, WORKSPACE_CONTEXT_MAX_TTL_SECONDS))
     throw new Error("Tenant assertion lifetime exceeds maximum TTL");
   return decoded;
 }
@@ -199640,6 +199655,27 @@ async function fetchRemoteImage(source, fetchImpl = fetch) {
   throw new Error("Remote image could not be fetched");
 }
 
+// ../../backend/src/lib/runtime-options.ts
+init_config();
+var RUNTIME_OPTIONS = Symbol.for("@hiai-gg/docsmint/runtime-options");
+function configureDocsMintRuntime(options = {}) {
+  const globals = globalThis;
+  const existing = globals[RUNTIME_OPTIONS];
+  if (existing)
+    return;
+  if (config3.DOCSMINT_WORKSPACE_ENABLED && !options.attachmentStorageQuotaAdmission) {
+    throw new Error("Attachment storage quota admission is required when workspace tenancy is enabled");
+  }
+  Object.defineProperty(globals, RUNTIME_OPTIONS, {
+    value: Object.freeze({ ...options }),
+    configurable: false,
+    writable: false
+  });
+}
+function getDocsMintRuntimeOptions() {
+  return globalThis[RUNTIME_OPTIONS];
+}
+
 // ../../backend/src/lib/share-access.ts
 init_schema2();
 init_drizzle_orm();
@@ -199919,6 +199955,31 @@ function attachmentKeyPrefix(ctx, userId, documentId) {
 }
 var PRESIGN_EXPIRY_SECONDS = config3.ATTACHMENT_PRESIGN_EXPIRY_SECONDS;
 var INTEGRITY_PROBE_BYTES = 8;
+function attachmentQuotaContext(ctx, actorUserId, documentId, storageKey, proposedSize) {
+  if (!config3.DOCSMINT_WORKSPACE_ENABLED)
+    return null;
+  if (!ctx.workspaceId)
+    return null;
+  return Object.freeze({
+    workspaceId: ctx.workspaceId,
+    actorUserId,
+    documentId,
+    storageKey,
+    proposedSize,
+    requestId: crypto.randomUUID(),
+    idempotencyKey: `attachment:${documentId}:${storageKey}`
+  });
+}
+function attachmentQuotaAdmission(set2) {
+  if (!config3.DOCSMINT_WORKSPACE_ENABLED)
+    return null;
+  const admission = getDocsMintRuntimeOptions()?.attachmentStorageQuotaAdmission;
+  if (!admission) {
+    set2.status = 503;
+    return;
+  }
+  return admission;
+}
 async function readStorageBody(body) {
   if (body == null) {
     return Buffer.alloc(0);
@@ -200069,15 +200130,42 @@ var attachmentRoutes = new Elysia({ prefix: "/api" }).post("/documents/:id/attac
   }
   const ext = filename.split(".").pop() ?? "bin";
   const key = `${attachmentKeyPrefix(ctx, userId, documentId)}/${nanoid3()}.${ext}`;
+  const quotaContext = attachmentQuotaContext(ctx, userId, documentId, key, size2);
+  const admission = attachmentQuotaAdmission(set2);
+  if (admission === undefined) {
+    return { error: "Attachment storage quota admission is unavailable" };
+  }
+  if (config3.DOCSMINT_WORKSPACE_ENABLED && !quotaContext) {
+    set2.status = 503;
+    return {
+      error: "Workspace context is required for attachment storage"
+    };
+  }
+  let reservationId;
+  if (admission && quotaContext) {
+    try {
+      reservationId = (await admission.reserve(quotaContext)).id;
+    } catch (error53) {
+      logger3.warn({ err: error53, documentId }, "Attachment storage quota reservation rejected");
+      set2.status = 413;
+      return { error: "Storage quota exceeded" };
+    }
+  }
   try {
     const url2 = await getSignedUrl(storagePublic, new PutObjectCommand({ Bucket: BUCKET, Key: key }), { expiresIn: PRESIGN_EXPIRY_SECONDS });
     return {
       url: url2,
       key,
+      ...reservationId ? { quotaReservationId: reservationId } : {},
       maxSize: ATTACHMENT_MAX_SIZE_BYTES,
       expiresIn: PRESIGN_EXPIRY_SECONDS
     };
   } catch (err) {
+    if (admission && quotaContext && reservationId) {
+      await admission.releaseReservation(quotaContext, reservationId).catch(() => {
+        return;
+      });
+    }
     logger3.error({ err, key }, "Failed to presign attachment upload");
     set2.status = 500;
     return { error: "Failed to generate upload URL" };
@@ -200110,6 +200198,7 @@ var attachmentRoutes = new Elysia({ prefix: "/api" }).post("/documents/:id/attac
   const filename = typeof payload?.filename === "string" ? payload.filename : "";
   const contentType = typeof payload?.contentType === "string" ? payload.contentType : "";
   const size2 = typeof payload?.size === "number" ? payload.size : -1;
+  const quotaReservationId = typeof payload?.quotaReservationId === "string" ? payload.quotaReservationId : "";
   if (!key) {
     set2.status = 400;
     return { error: "key is required" };
@@ -200137,15 +200226,50 @@ var attachmentRoutes = new Elysia({ prefix: "/api" }).post("/documents/:id/attac
       error: `File too large. Maximum size: ${ATTACHMENT_MAX_SIZE_BYTES / 1024 / 1024}MB`
     };
   }
+  const quotaContext = attachmentQuotaContext(ctx, userId, documentId, key, size2);
+  const admission = attachmentQuotaAdmission(set2);
+  if (admission === undefined) {
+    return { error: "Attachment storage quota admission is unavailable" };
+  }
+  if (config3.DOCSMINT_WORKSPACE_ENABLED && !quotaContext) {
+    set2.status = 503;
+    return {
+      error: "Workspace context is required for attachment storage"
+    };
+  }
+  if (admission && quotaContext && !quotaReservationId) {
+    set2.status = 400;
+    return { error: "quotaReservationId is required" };
+  }
   let headOutput;
   try {
     headOutput = await storage.send(new HeadObjectCommand({ Bucket: BUCKET, Key: key }));
   } catch (err) {
+    if (admission && quotaContext && quotaReservationId) {
+      await admission.releaseReservation(quotaContext, quotaReservationId).catch(() => {
+        return;
+      });
+    }
     logger3.warn({ err, key }, "Confirm failed: object not in storage");
     set2.status = 409;
     return { error: "Upload not found in storage \u2014 please retry upload" };
   }
   const storedSize = headOutput.ContentLength ?? size2;
+  if (admission && quotaContext && quotaReservationId) {
+    try {
+      await admission.finalize(quotaContext, {
+        reservationId: quotaReservationId,
+        actualSize: storedSize
+      });
+    } catch (error53) {
+      await admission.releaseReservation(quotaContext, quotaReservationId).catch(() => {
+        return;
+      });
+      logger3.error({ err: error53, documentId }, "Attachment storage quota finalization failed");
+      set2.status = 503;
+      return { error: "Attachment storage quota finalization failed" };
+    }
+  }
   try {
     const created = await withTenant(ctx, async (tx) => {
       const [row] = await tx.insert(attachments).values({
@@ -200158,6 +200282,11 @@ var attachmentRoutes = new Elysia({ prefix: "/api" }).post("/documents/:id/attac
       return row ?? null;
     });
     if (!created) {
+      if (admission && quotaContext && quotaReservationId) {
+        await admission.releaseCommitted(quotaContext).catch(() => {
+          return;
+        });
+      }
       set2.status = 500;
       return { error: "Failed to save attachment record" };
     }
@@ -200170,6 +200299,11 @@ var attachmentRoutes = new Elysia({ prefix: "/api" }).post("/documents/:id/attac
       url: `/api/attachments/${created.id}/raw`
     };
   } catch (err) {
+    if (admission && quotaContext && quotaReservationId) {
+      await admission.releaseCommitted(quotaContext).catch(() => {
+        return;
+      });
+    }
     logger3.error({ err, key }, "Confirm failed: DB insert error");
     set2.status = 500;
     return { error: "Failed to save attachment record" };
@@ -200194,6 +200328,12 @@ var attachmentRoutes = new Elysia({ prefix: "/api" }).post("/documents/:id/attac
   }
   const ctx = authorization.access.ctx;
   const userId = authorization.access.userId;
+  if (config3.DOCSMINT_WORKSPACE_ENABLED) {
+    set2.status = 503;
+    return {
+      error: "Legacy attachment uploads are unavailable with workspace storage enforcement"
+    };
+  }
   const documentId = params.id;
   let file3;
   try {
@@ -200320,7 +200460,9 @@ var attachmentRoutes = new Elysia({ prefix: "/api" }).post("/documents/:id/attac
   const row = await withTenant(ctx, async (tx) => {
     const [r4] = await tx.select({
       id: attachments.id,
+      documentId: attachments.documentId,
       storageKey: attachments.storageKey,
+      size: attachments.size,
       ownerId: documents.ownerId,
       categoryId: documents.categoryId,
       folderCategoryId: folders.categoryId
@@ -200339,6 +200481,15 @@ var attachmentRoutes = new Elysia({ prefix: "/api" }).post("/documents/:id/attac
     set2.status = 403;
     return { error: "Forbidden" };
   }
+  const quotaContext = attachmentQuotaContext(ctx, userId, row.documentId, row.storageKey, row.size);
+  const admission = attachmentQuotaAdmission(set2);
+  if (admission === undefined) {
+    return { error: "Attachment storage quota admission is unavailable" };
+  }
+  if (config3.DOCSMINT_WORKSPACE_ENABLED && !quotaContext) {
+    set2.status = 503;
+    return { error: "Workspace context is required for attachment storage" };
+  }
   try {
     await storage.send(new DeleteObjectCommand({ Bucket: BUCKET, Key: row.storageKey }));
   } catch (err) {
@@ -200347,6 +200498,13 @@ var attachmentRoutes = new Elysia({ prefix: "/api" }).post("/documents/:id/attac
   await withTenant(ctx, async (tx) => {
     await tx.delete(attachments).where(eq(attachments.id, attachmentId));
   });
+  if (admission && quotaContext) {
+    try {
+      await admission.releaseCommitted(quotaContext);
+    } catch (error53) {
+      logger3.error({ err: error53, attachmentId }, "Attachment storage quota release failed after delete");
+    }
+  }
   return { success: true };
 }).get("/attachments/:id/raw", async ({ params, request, set: set2 }) => {
   try {
@@ -206949,6 +207107,18 @@ async function invalidateDocCache(docId) {
   }
 }
 
+// ../../backend/src/lib/document-create-idempotency.ts
+var IDEMPOTENCY_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+function documentCreateIdempotencyKey(request) {
+  const value = request.headers.get("idempotency-key");
+  if (value === null)
+    return null;
+  return IDEMPOTENCY_KEY_PATTERN.test(value) ? value : "invalid";
+}
+function documentCreateWorkspaceIdentity(userId, workspaceId) {
+  return workspaceId ?? `personal:${userId}`;
+}
+
 // ../../backend/src/lib/docx-parser.ts
 var import_mammoth = __toESM(require_lib7(), 1);
 
@@ -207404,14 +207574,6 @@ var documentRoutes = new Elysia({ prefix: "/api" }).get("/documents", async ({ q
     return { error: "Failed to list documents" };
   }
 }).post("/documents", async ({ request, set: set2 }) => {
-  const ip = request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ?? request.headers.get("x-real-ip") ?? "unknown";
-  const rl = await writeRateLimiter(ip, request);
-  if (!rl.allowed) {
-    set2.status = 429;
-    set2.headers = rateLimitHeaders(0, rl.retryAfter);
-    return { error: "Too many requests" };
-  }
-  set2.headers = rateLimitHeaders(rl.remaining);
   const access = await resolveContentAccess(request);
   const ctx = access.ctx;
   if (ctx.role === "none") {
@@ -207423,6 +207585,30 @@ var documentRoutes = new Elysia({ prefix: "/api" }).get("/documents", async ({ q
     return { error: "Forbidden" };
   }
   const userId = ctx.userId;
+  const idempotencyKey = documentCreateIdempotencyKey(request);
+  if (idempotencyKey === "invalid") {
+    set2.status = 400;
+    return { error: "Invalid Idempotency-Key" };
+  }
+  if (idempotencyKey) {
+    const workspaceIdentity = documentCreateWorkspaceIdentity(userId, ctx.workspaceId);
+    const replay = await withTenant(ctx, async (tx) => {
+      const [existing] = await tx.select({ document: documents }).from(documentCreateOperations).innerJoin(documents, eq(documentCreateOperations.documentId, documents.id)).where(and(eq(documentCreateOperations.workspaceId, workspaceIdentity), eq(documentCreateOperations.actorUserId, userId), eq(documentCreateOperations.idempotencyKey, idempotencyKey))).limit(1);
+      return existing?.document ?? null;
+    });
+    if (replay) {
+      set2.status = 200;
+      return replay;
+    }
+  }
+  const ip = request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ?? request.headers.get("x-real-ip") ?? "unknown";
+  const rl = await writeRateLimiter(ip, request);
+  if (!rl.allowed) {
+    set2.status = 429;
+    set2.headers = rateLimitHeaders(0, rl.retryAfter);
+    return { error: "Too many requests" };
+  }
+  set2.headers = rateLimitHeaders(rl.remaining);
   const body = createDocumentSchema.safeParse(await request.json());
   if (!body.success) {
     set2.status = 400;
@@ -207441,9 +207627,17 @@ var documentRoutes = new Elysia({ prefix: "/api" }).get("/documents", async ({ q
       set2.status = 403;
       return { error: "Forbidden" };
     }
-    const created = await withTenant(ctx, async (tx) => {
+    const createdResult = await withTenant(ctx, async (tx) => {
+      const workspaceIdentity = documentCreateWorkspaceIdentity(userId, ctx.workspaceId);
+      if (idempotencyKey) {
+        await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtext(${`${workspaceIdentity}:${userId}:${idempotencyKey}`}))`);
+        const [existing] = await tx.select({ document: documents }).from(documentCreateOperations).innerJoin(documents, eq(documentCreateOperations.documentId, documents.id)).where(and(eq(documentCreateOperations.workspaceId, workspaceIdentity), eq(documentCreateOperations.actorUserId, userId), eq(documentCreateOperations.idempotencyKey, idempotencyKey))).limit(1);
+        if (existing)
+          return { row: existing.document, replayed: true };
+      }
       const [row] = await tx.insert(documents).values({
         ownerId: userId,
+        workspaceId: ctx.workspaceId ?? null,
         title: body.data.title,
         content: initialContent,
         contentHash: initialHash,
@@ -207461,8 +207655,21 @@ var documentRoutes = new Elysia({ prefix: "/api" }).get("/documents", async ({ q
         contentJson: null,
         createdBy: userId
       });
-      return row;
+      if (idempotencyKey) {
+        await tx.insert(documentCreateOperations).values({
+          workspaceId: workspaceIdentity,
+          actorUserId: userId,
+          idempotencyKey,
+          documentId: row.id
+        });
+      }
+      return { row, replayed: false };
     });
+    const created = createdResult.row;
+    if (createdResult.replayed) {
+      set2.status = 200;
+      return created;
+    }
     enqueueDocumentPipeline({
       documentId: created.id,
       ownerId: userId,
@@ -213875,6 +214082,7 @@ async function closeRuntime(options, workers) {
 }
 
 // ../../backend/src/index.ts
+configureDocsMintRuntime();
 await ensureApiKeyOwner();
 configureDefaultJobOptions({
   attempts: config3.QUEUE_JOB_ATTEMPTS,
@@ -213941,7 +214149,7 @@ var swaggerConfig = {
   documentation: {
     info: {
       title: "DocsMint API",
-      version: "0.3.5",
+      version: "0.3.7",
       description: "Self-hosted AI-first documentation platform. Full-text + semantic search, version history, sharing, and folder organization.",
       contact: { name: "HiAi-gg", url: "https://github.com/HiAi-gg/docsmint" },
       license: {
@@ -214010,11 +214218,17 @@ app.listen({
   idleTimeout: 30
 });
 logger3.info({ port: config3.API_PORT }, "hiai-docs API started");
-var shutdown = async () => {
+var stopDocsMintApi = async () => {
   logger3.info("Shutting down...");
   await pipelineRuntime.close();
   await app.stop();
+};
+var shutdown = async () => {
+  await stopDocsMintApi();
   process.exit(0);
 };
 process.on("SIGTERM", shutdown);
 process.on("SIGINT", shutdown);
+export {
+  stopDocsMintApi
+};

package/dist/backend-launcher.d.ts

@@ -35,6 +35,21 @@ export type DocsmintBackendHandle = Readonly<{
 export type DocsmintBackendLauncher = Readonly<{
     launch(options?: LaunchDocsmintBackendOptions): DocsmintBackendHandle;
 }>;
+import type { AttachmentStorageQuotaAdmission } from "./storage-quota";
+export type { AttachmentStorageQuotaAdmission } from "./storage-quota";
+export type DocsMintRuntimeOptions = Readonly<{
+    attachmentStorageQuotaAdmission?: AttachmentStorageQuotaAdmission;
+}>;
+export type DocsMintInProcessHandle = Readonly<{
+    ready: Promise<void>;
+    stop(): Promise<void>;
+}>;
+/**
+ * Starts the bundled OSS API in this Bun process. Runtime options are frozen
+ * and installed before importing the backend graph, so routes/workers cannot
+ * observe an unconfigured tenancy-enabled process.
+ */
+export declare function launchDocsMintApi(options?: DocsMintRuntimeOptions): Promise<DocsMintInProcessHandle>;
 export declare function resolveDocsmintBackendEntrypoint(launcherModuleUrl?: string | URL): URL;
 export declare function createDocsmintBackendLauncher(runtime: DocsmintBackendLauncherRuntime): DocsmintBackendLauncher;
 export declare function launchDocsmintBackend(options?: LaunchDocsmintBackendOptions): DocsmintBackendHandle;

package/dist/backend-launcher.js

@@ -1,4 +1,26 @@
 /** Server-only launcher for the bundled DocsMint backend runtime. */
+const RUNTIME_OPTIONS = Symbol.for("@hiai-gg/docsmint/runtime-options");
+/**
+ * Starts the bundled OSS API in this Bun process. Runtime options are frozen
+ * and installed before importing the backend graph, so routes/workers cannot
+ * observe an unconfigured tenancy-enabled process.
+ */
+export async function launchDocsMintApi(options = {}) {
+    if (process.env.DOCSMINT_WORKSPACE_ENABLED === "true" &&
+        !options.attachmentStorageQuotaAdmission) {
+        throw new Error("Attachment storage quota admission is required when workspace tenancy is enabled");
+    }
+    const globals = globalThis;
+    if (globals[RUNTIME_OPTIONS])
+        throw new Error("DocsMint runtime is already configured");
+    globals[RUNTIME_OPTIONS] = Object.freeze({ ...options });
+    const backendUrl = new URL("./backend/index.js", import.meta.url).href;
+    const backend = (await import(backendUrl));
+    return Object.freeze({
+        ready: Promise.resolve(),
+        stop: async () => backend.stopDocsMintApi?.(),
+    });
+}
 const DEFAULT_STARTUP_TIMEOUT_MS = 30_000;
 const DEFAULT_POLL_INTERVAL_MS = 200;
 const DEFAULT_API_PORT = "50700";