@hiai-gg/docsmint 0.3.4 → 0.3.6

package/dist/backend-launcher.d.ts

@@ -0,0 +1,55 @@
+/** Server-only launcher for the bundled DocsMint backend runtime. */
+export type DocsmintBackendEnvironment = Readonly<Record<string, string | undefined>>;
+export type LaunchDocsmintBackendOptions = Readonly<{
+    cwd?: string;
+    env?: DocsmintBackendEnvironment;
+    healthUrl?: string;
+    startupTimeoutMs?: number;
+    pollIntervalMs?: number;
+    signal?: AbortSignal;
+}>;
+export type DocsmintBackendProcess = Readonly<{
+    pid: number;
+    exited: Promise<number>;
+    kill(signal: "SIGTERM" | "SIGKILL"): void;
+}>;
+export type DocsmintBackendSpawnSpec = Readonly<{
+    command: readonly string[];
+    cwd?: string;
+    env: Readonly<Record<string, string>>;
+}>;
+export type DocsmintBackendLauncherRuntime = Readonly<{
+    executable: string;
+    launcherModuleUrl?: string | URL;
+    spawn(spec: DocsmintBackendSpawnSpec): DocsmintBackendProcess;
+    fetch(input: string, init?: RequestInit): Promise<Response>;
+    now?: () => number;
+    sleep?: (milliseconds: number) => Promise<void>;
+}>;
+export type DocsmintBackendHandle = Readonly<{
+    pid: number;
+    ready: Promise<void>;
+    exited: Promise<number>;
+    stop(): Promise<void>;
+}>;
+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

@@ -0,0 +1,136 @@
+/** 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";
+function assertPositiveMilliseconds(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new TypeError(`${name} must be a positive safe integer`);
+    }
+}
+function immutableEnvironment(overrides = {}) {
+    const merged = {};
+    for (const [key, value] of Object.entries({ ...process.env, ...overrides })) {
+        if (typeof value === "string")
+            merged[key] = value;
+    }
+    return Object.freeze(merged);
+}
+export function resolveDocsmintBackendEntrypoint(launcherModuleUrl = import.meta.url) {
+    return new URL("./backend/index.js", launcherModuleUrl);
+}
+function defaultRuntime() {
+    if (typeof Bun === "undefined") {
+        throw new Error("DocsMint backend launcher requires the Bun runtime");
+    }
+    return {
+        executable: Bun.argv[0] ?? "bun",
+        spawn(spec) {
+            const child = Bun.spawn({
+                cmd: [...spec.command],
+                ...(spec.cwd ? { cwd: spec.cwd } : {}),
+                env: { ...spec.env },
+                stdout: "inherit",
+                stderr: "inherit",
+            });
+            return {
+                pid: child.pid,
+                exited: child.exited,
+                kill(signal) {
+                    child.kill(signal);
+                },
+            };
+        },
+        fetch: (input, init) => fetch(input, init),
+        now: Date.now,
+        sleep: (milliseconds) => Bun.sleep(milliseconds),
+    };
+}
+export function createDocsmintBackendLauncher(runtime) {
+    const now = runtime.now ?? Date.now;
+    const sleep = runtime.sleep ?? ((milliseconds) => Bun.sleep(milliseconds));
+    return Object.freeze({
+        launch(options = {}) {
+            const startupTimeoutMs = options.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
+            const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+            assertPositiveMilliseconds(startupTimeoutMs, "startupTimeoutMs");
+            assertPositiveMilliseconds(pollIntervalMs, "pollIntervalMs");
+            if (options.signal?.aborted) {
+                throw new DOMException("Backend launch aborted", "AbortError");
+            }
+            const env = immutableEnvironment(options.env);
+            const port = env.API_PORT ?? DEFAULT_API_PORT;
+            const healthUrl = options.healthUrl ?? `http://127.0.0.1:${port}/api/health`;
+            const entrypoint = resolveDocsmintBackendEntrypoint(runtime.launcherModuleUrl ?? import.meta.url);
+            const child = runtime.spawn(Object.freeze({
+                command: Object.freeze([runtime.executable, entrypoint.pathname]),
+                ...(options.cwd ? { cwd: options.cwd } : {}),
+                env,
+            }));
+            let stopped = false;
+            const stop = async () => {
+                if (stopped)
+                    return;
+                stopped = true;
+                child.kill("SIGTERM");
+            };
+            const ready = (async () => {
+                const deadline = now() + startupTimeoutMs;
+                try {
+                    while (now() <= deadline) {
+                        if (options.signal?.aborted) {
+                            throw new DOMException("Backend launch aborted", "AbortError");
+                        }
+                        try {
+                            const response = await runtime.fetch(healthUrl, {
+                                signal: options.signal,
+                            });
+                            if (response.ok)
+                                return;
+                        }
+                        catch (error) {
+                            if (options.signal?.aborted)
+                                throw error;
+                        }
+                        await sleep(pollIntervalMs);
+                    }
+                    throw new Error(`DocsMint backend did not become ready within ${startupTimeoutMs}ms`);
+                }
+                catch (error) {
+                    await stop();
+                    throw error;
+                }
+            })();
+            return Object.freeze({
+                pid: child.pid,
+                ready,
+                exited: child.exited,
+                stop,
+            });
+        },
+    });
+}
+export function launchDocsmintBackend(options = {}) {
+    return createDocsmintBackendLauncher(defaultRuntime()).launch(options);
+}

package/dist/frontend/extension.d.ts

@@ -25,7 +25,8 @@ export interface SettingsSectionExtension { id: string; label: string; component
 export interface CommandPaletteActionContext { query?: string; }
 export type CommandPaletteAction = (context: CommandPaletteActionContext) => void | Promise<void>;
 export interface CommandPaletteActionExtension { id: string; label: string; keywords?: readonly string[]; group?: string; shortcut?: string; icon?: ExtensionIcon; order?: number; disabled?: boolean; visible?: ExtensionVisibility; run: CommandPaletteAction; }
-export interface SharedDocumentExtensionContext { shareToken: string; documentId: string; title: string; content: string; contentJson?: object; role: "viewer" | "commenter" | "editor"; permissions: { read: true; annotate: boolean; edit: boolean; export: boolean; }; }
+export interface SharedDocumentExtensionCapability { id: string; expiresAt: string; }
+export interface SharedDocumentExtensionContext { documentId: string; title: string; content: string; contentJson?: object; role: "viewer" | "commenter" | "editor"; capability: SharedDocumentExtensionCapability; permissions: { read: true; annotate: boolean; edit: boolean; export: boolean; }; }
 export interface SharedDocumentExtension { id: string; label: string; icon?: ExtensionIcon; order?: number; permission: "annotate" | "edit"; visible?: (context: SharedDocumentExtensionContext) => boolean; component: Component<{ context: SharedDocumentExtensionContext }>; }
 export interface DocsmintFrontendExtensions { navigation: readonly NavigationExtension[]; dashboardWidgets: readonly DashboardWidgetExtension[]; searchWidgets: readonly SearchWidgetExtension[]; documentTabs: readonly DocTabDefinition[]; editorActions: readonly EditorActionExtension[]; documentMenuActions: readonly DocumentMenuActionExtension[]; settingsSections: readonly SettingsSectionExtension[]; commandPaletteActions: readonly CommandPaletteActionExtension[]; sharedDocumentHeaderActions: readonly SharedDocumentExtension[]; sharedDocumentTabs: readonly SharedDocumentExtension[]; sharedDocumentNotesModes: readonly SharedDocumentExtension[]; sharedDocumentEditorModes: readonly SharedDocumentExtension[]; }
 /** @deprecated Use DocsmintFrontendExtensions. */

package/dist/frontend/shared-document.js

@@ -1,15 +1,15 @@
 import { t as e } from "./context-DbnW5yib.js";
-import { $ as t, D as n, H as r, M as i, N as a, S as o, T as s, _t as c, dt as l, et as u, ft as d, j as f, k as p, tt as m } from "./client-C6QQGb0e.js";
+import { $ as t, D as n, H as r, M as i, N as a, S as o, T as s, _t as c, dt as l, et as u, ft as d, j as f, k as p, lt as m, tt as h } from "./client-C6QQGb0e.js";
 //#region src/lib/components/editor/shared-document.ts
-var h = /^\/api\/attachments\/[0-9a-f-]+\/raw$/i, g = /* @__PURE__ */ new Set([
+var g = /^\/api\/attachments\/[0-9a-f-]+\/raw$/i, _ = /* @__PURE__ */ new Set([
 	"http:",
 	"https:",
 	"mailto:"
 ]);
-function _(e) {
+function v(e) {
 	return e.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
-function v(e, t) {
+function y(e, t) {
 	switch (e.type) {
 		case "bold": return `<strong>${t}</strong>`;
 		case "italic": return `<em>${t}</em>`;
@@ -17,41 +17,41 @@ function v(e, t) {
 		case "strikethrough": return `<s>${t}</s>`;
 		case "underline": return `<u>${t}</u>`;
 		case "code": return `<code>${t}</code>`;
-		case "link": return `<a href="${_(y(e.attrs?.href ?? "#"))}" target="_blank" rel="noopener noreferrer">${t}</a>`;
-		case "highlight": return `<mark style="background-color: ${_(e.attrs?.color ?? "#fde68a")}">${t}</mark>`;
+		case "link": return `<a href="${v(b(e.attrs?.href ?? "#"))}" target="_blank" rel="noopener noreferrer">${t}</a>`;
+		case "highlight": return `<mark style="background-color: ${v(e.attrs?.color ?? "#fde68a")}">${t}</mark>`;
 		default: return t;
 	}
 }
-function y(e) {
+function b(e) {
 	if (e.startsWith("#") || e.startsWith("/") || e.startsWith("./")) return e;
 	try {
 		let t = new URL(e);
-		return g.has(t.protocol) ? e : "#";
+		return _.has(t.protocol) ? e : "#";
 	} catch {
 		return "#";
 	}
 }
-function b(e) {
+function x(e) {
 	let t = e?.textAlign;
 	return t !== "left" && t !== "center" && t !== "right" && t !== "justify" ? "" : ` style="text-align: ${t}"`;
 }
-function x(e) {
+function S(e) {
 	if (e.type === "text") {
-		let t = _(e.text ?? "");
-		for (let n of e.marks ?? []) t = v(n, t);
+		let t = v(e.text ?? "");
+		for (let n of e.marks ?? []) t = y(n, t);
 		return t;
 	}
-	return (e.content ?? []).map(x).join("");
+	return (e.content ?? []).map(S).join("");
 }
-function S(e) {
+function C(e) {
 	let t = (e) => {
-		if (e.type === "text") return x(e);
-		let n = b(e.attrs), r = (e.content ?? []).map(t).join("");
+		if (e.type === "text") return S(e);
+		let n = x(e.attrs), r = (e.content ?? []).map(t).join("");
 		switch (e.type) {
 			case "paragraph": return `<p${n}>${r}</p>`;
 			case "heading": {
 				let t = Math.min(Math.max(Number(e.attrs?.level ?? 1), 1), 6);
-				return `<h${t}${n}>${(e.content ?? []).map(x).join("")}</h${t}>`;
+				return `<h${t}${n}>${(e.content ?? []).map(S).join("")}</h${t}>`;
 			}
 			case "bulletList": return `<ul${n}>${r}</ul>`;
 			case "orderedList": {
@@ -71,34 +71,34 @@ function S(e) {
 			case "tableCell": return `<td${n}>${r}</td>`;
 			case "codeBlock": {
 				let t = e.attrs?.language ?? "";
-				return `<pre><code${t ? ` class="language-${_(t)}"` : ""}>${r}</code></pre>`;
+				return `<pre><code${t ? ` class="language-${v(t)}"` : ""}>${r}</code></pre>`;
 			}
 			case "horizontalRule": return "<hr />";
 			case "hardBreak": return "<br />";
 			case "image": {
 				let t = e.attrs?.src ?? "", n = e.attrs?.alt ?? "", r = Number(e.attrs?.width), i = Number(e.attrs?.height), a = `${Number.isFinite(r) && r > 0 ? ` width="${Math.round(r)}"` : ""}${Number.isFinite(i) && i > 0 ? ` height="${Math.round(i)}"` : ""}`;
-				return h.test(t) ? `<img data-shared-attachment-src="${_(t)}" alt="${_(n)}"${a} />` : `<img src="${_(t)}" alt="${_(n)}"${a} />`;
+				return g.test(t) ? `<img data-shared-attachment-src="${v(t)}" alt="${v(n)}"${a} />` : `<img src="${v(t)}" alt="${v(n)}"${a} />`;
 			}
 			default: return r;
 		}
 	};
 	return (e.content ?? []).map(t).join("");
 }
-function C(e) {
+function w(e) {
 	return e.replace(/<li>(\s*<input\b[^>]*type=["']checkbox["'][^>]*>)/gi, "<li class=\"task-list-item\">$1");
 }
-function w(e, t = "") {
+function T(e, t = "") {
 	return {
 		"x-share-token": e,
 		...t ? { "x-share-password": t } : {}
 	};
 }
-async function T(e, t, n = "") {
+async function E(e, t, n = "") {
 	let r = [], i = e.querySelectorAll("img[data-shared-attachment-src]");
 	return await Promise.all(Array.from(i, async (e) => {
 		let i = e.dataset.sharedAttachmentSrc;
 		if (i) try {
-			let a = await fetch(i, { headers: w(t, n) });
+			let a = await fetch(i, { headers: T(t, n) });
 			if (!a.ok) {
 				e.dataset.sharedAttachmentError = String(a.status);
 				return;
@@ -110,7 +110,7 @@ async function T(e, t, n = "") {
 		}
 	})), r;
 }
-async function E(e) {
+async function D(e) {
 	let t = Array.from(e.querySelectorAll("img"));
 	await Promise.all(t.map(async (e) => {
 		if (!e.complete) {
@@ -125,69 +125,104 @@ async function E(e) {
 	}));
 }
 //#endregion
+//#region src/lib/extensions/shared-document-context.ts
+var O = /* @__PURE__ */ new Set([
+	"shareToken",
+	"password",
+	"passwordHash",
+	"workspaceAssertion",
+	"authorization",
+	"cookie",
+	"signingSecret"
+]);
+function k(e) {
+	if (!e.id.trim() || !e.expiresAt.trim()) throw TypeError("Shared extension capability must include a non-empty id and expiry");
+	return Object.freeze({
+		id: e.id,
+		expiresAt: e.expiresAt
+	});
+}
+function A(e) {
+	for (let t of Object.keys(e)) if (O.has(t)) throw TypeError(`Sensitive ${t} must not be provided to a shared extension`);
+	return Object.freeze({
+		documentId: e.documentId,
+		title: e.title,
+		content: e.content,
+		...e.contentJson === void 0 ? {} : { contentJson: e.contentJson },
+		role: e.role,
+		capability: k(e.capability),
+		permissions: Object.freeze({
+			read: !0,
+			annotate: e.permissions.annotate,
+			edit: e.permissions.edit,
+			export: e.permissions.export
+		})
+	});
+}
+//#endregion
 //#region src/lib/hosts/DocsmintSharedDocumentHost.svelte
-var D = a("<div data-docsmint-shared-document-host=\"\"><div data-extension-zone=\"shared-header-actions\"></div> <!> <div data-extension-zone=\"shared-document-tabs\"></div> <div data-extension-zone=\"shared-document-notes\"></div> <div data-extension-zone=\"shared-document-editor\"><!></div></div>");
-function O(a, h) {
-	d(h, !0);
-	let g = e();
-	function _(e) {
-		return e.permission === "annotate" ? h.context.permissions.annotate : h.context.permissions.edit;
+var j = a("<div data-docsmint-shared-document-host=\"\"><div data-extension-zone=\"shared-header-actions\"></div> <!> <div data-extension-zone=\"shared-document-tabs\"></div> <div data-extension-zone=\"shared-document-notes\"></div> <div data-extension-zone=\"shared-document-editor\"><!></div></div>");
+function M(a, g) {
+	d(g, !0);
+	let _ = e(), v = m(() => A(g.context));
+	function y(e) {
+		return e.permission === "annotate" ? r(v).permissions.annotate : r(v).permissions.edit;
 	}
-	function v(e) {
+	function b(e) {
 		let t = /* @__PURE__ */ new Set();
 		return e.filter((e) => {
-			if (t.has(e.id) || !_(e)) return !1;
+			if (t.has(e.id) || !y(e)) return !1;
 			t.add(e.id);
 			try {
-				return e.visible?.(h.context) ?? !0;
+				return e.visible?.(r(v)) ?? !0;
 			} catch {
 				return !1;
 			}
 		}).sort((e, t) => (e.order ?? 0) - (t.order ?? 0) || e.id.localeCompare(t.id));
 	}
-	var y = D(), b = t(y);
-	s(b, 21, () => v(g.sharedDocumentHeaderActions), (e) => e.id, (e, t) => {
+	var x = j(), S = t(x);
+	s(S, 21, () => b(_.sharedDocumentHeaderActions), (e) => e.id, (e, t) => {
 		var n = i();
 		o(u(n), () => r(t).component, (e, t) => {
 			t(e, { get context() {
-				return h.context;
+				return r(v);
 			} });
 		}), f(e, n);
-	}), c(b);
-	var x = m(b, 2);
-	p(x, () => h.children);
-	var S = m(x, 2);
-	s(S, 21, () => v(g.sharedDocumentTabs), (e) => e.id, (e, t) => {
+	}), c(S);
+	var C = h(S, 2);
+	p(C, () => g.children);
+	var w = h(C, 2);
+	s(w, 21, () => b(_.sharedDocumentTabs), (e) => e.id, (e, t) => {
 		var n = i();
 		o(u(n), () => r(t).component, (e, t) => {
 			t(e, { get context() {
-				return h.context;
+				return r(v);
 			} });
 		}), f(e, n);
-	}), c(S);
-	var C = m(S, 2);
-	s(C, 21, () => v(g.sharedDocumentNotesModes), (e) => e.id, (e, t) => {
+	}), c(w);
+	var T = h(w, 2);
+	s(T, 21, () => b(_.sharedDocumentNotesModes), (e) => e.id, (e, t) => {
 		var n = i();
 		o(u(n), () => r(t).component, (e, t) => {
 			t(e, { get context() {
-				return h.context;
+				return r(v);
 			} });
 		}), f(e, n);
-	}), c(C);
-	var w = m(C, 2), T = t(w), E = (e) => {
+	}), c(T);
+	var E = h(T, 2), D = t(E), O = (e) => {
 		var t = i();
-		s(u(t), 17, () => v(g.sharedDocumentEditorModes), (e) => e.id, (e, t) => {
+		s(u(t), 17, () => b(_.sharedDocumentEditorModes), (e) => e.id, (e, t) => {
 			var n = i();
 			o(u(n), () => r(t).component, (e, t) => {
 				t(e, { get context() {
-					return h.context;
+					return r(v);
 				} });
 			}), f(e, n);
 		}), f(e, t);
 	};
-	n(T, (e) => {
-		h.context.permissions.edit && e(E);
-	}), c(w), c(y), f(a, y), l();
+	n(D, (e) => {
+		r(v).permissions.edit && e(O);
+	}), c(E), c(x), f(a, x), l();
 }
 //#endregion
-export { O as DocsmintSharedDocumentHost, T as hydrateSharedAttachmentImages, C as markMarkdownTaskItems, S as renderSharedDocument, w as sharedAttachmentHeaders, E as waitForSharedDocumentImages };
+export { M as DocsmintSharedDocumentHost, E as hydrateSharedAttachmentImages, w as markMarkdownTaskItems, C as renderSharedDocument, T as sharedAttachmentHeaders, D as waitForSharedDocumentImages };

package/dist/lifecycle-persistent.d.ts

@@ -0,0 +1,31 @@
+import { type AssertPurgeAllowed, type LifecycleHostStep, type UserDataLifecycle, type UserDataLifecycleAdapter } from "./lifecycle";
+/**
+ * Minimal transaction boundary required by the durable lifecycle runtime.
+ * Hosts supply a request/RLS-scoped executor; SDK code never imports a global
+ * database singleton or bypasses host tenant policy.
+ */
+export type LifecycleScopedDatabaseExecutor = <T>(context: Readonly<{
+    actorUserId: string;
+    requestId: string;
+    signal?: AbortSignal;
+}>, operation: () => Promise<T>) => Promise<T>;
+/**
+ * Public persistent lifecycle composition contract.  The OSS persistence
+ * saga is supplied by the backend runtime; SaaS hosts attach their own steps
+ * and RLS executor without private imports.
+ */
+export type LifecycleRuntimeAdapters = Readonly<{
+    database: LifecycleScopedDatabaseExecutor;
+    adapter: UserDataLifecycleAdapter;
+}>;
+export type PersistentLifecycleRuntimeOptions = Readonly<{
+    runtime: LifecycleRuntimeAdapters;
+    assertPurgeAllowed: AssertPurgeAllowed;
+    hostSteps?: readonly LifecycleHostStep[];
+}>;
+/**
+ * Creates an immutable, transaction-scoped public lifecycle facade.
+ * The database executor is invoked for every OSS adapter operation so hosts
+ * can set RLS GUCs and reject a missing scope before any mutation occurs.
+ */
+export declare function createPersistentLifecycleRuntime(options: PersistentLifecycleRuntimeOptions): UserDataLifecycle;

package/dist/lifecycle-persistent.js

@@ -0,0 +1,33 @@
+import { createUserDataLifecycle, orderLifecycleHostSteps, } from "./lifecycle";
+function immutableContext(context) {
+    return Object.freeze({ ...context });
+}
+/**
+ * Creates an immutable, transaction-scoped public lifecycle facade.
+ * The database executor is invoked for every OSS adapter operation so hosts
+ * can set RLS GUCs and reject a missing scope before any mutation occurs.
+ */
+export function createPersistentLifecycleRuntime(options) {
+    const hostSteps = orderLifecycleHostSteps(options.hostSteps ?? []);
+    const lifecycle = createUserDataLifecycle({
+        async *exportUserData(context) {
+            const immutable = immutableContext(context);
+            const records = await options.runtime.database(immutable, async () => {
+                const result = [];
+                for await (const record of options.runtime.adapter.exportUserData(immutable))
+                    result.push(record);
+                return result;
+            });
+            for (const record of records)
+                yield record;
+        },
+        async purgeUserData(context, gate) {
+            const immutable = immutableContext(context);
+            return options.runtime.database(immutable, () => options.runtime.adapter.purgeUserData(immutable, gate));
+        },
+    }, async (context) => options.assertPurgeAllowed(immutableContext(context)));
+    // Validate host-step ordering eagerly. The OSS adapter owns invocation; the
+    // public factory records the accepted contract without inventing SaaS data.
+    void hostSteps;
+    return lifecycle;
+}

package/dist/server-only-browser-entry.js

@@ -0,0 +1,3 @@
+"use strict";
+/** Browser-condition guard for every server-only public subpath. */
+throw new Error("This @hiai-gg/docsmint entrypoint is server-only");

package/dist/storage-quota.d.ts

@@ -0,0 +1,92 @@
+/** Server-only, persistence-agnostic storage quota contract. */
+export type StorageQuotaContext = Readonly<{
+    actorUserId: string;
+    requestId: string;
+    idempotencyKey: string;
+    signal?: AbortSignal;
+}>;
+export type StorageQuotaReservationRequest = StorageQuotaContext & Readonly<{
+    bytes: number;
+}>;
+export type StorageQuotaReservation = Readonly<{
+    status: "reserved" | "already_reserved";
+    reservationId: string;
+    reservedBytes: number;
+    usageBytes: number;
+    limitBytes: number;
+    expiresAt: string;
+}>;
+export type StorageQuotaRejection = Readonly<{
+    status: "rejected";
+    usageBytes: number;
+    limitBytes: number;
+    requestedBytes: number;
+}>;
+export type StorageQuotaCommitRequest = StorageQuotaContext & Readonly<{
+    reservationId: string;
+    actualBytes: number;
+}>;
+export type StorageQuotaReleaseRequest = StorageQuotaContext & Readonly<{
+    reservationId: string;
+}>;
+export type StorageQuotaCommitResult = Readonly<{
+    status: "committed" | "already_committed";
+}>;
+export type StorageQuotaReleaseResult = Readonly<{
+    status: "released" | "already_released" | "not_found";
+}>;
+export type StorageQuotaAdapter = Readonly<{
+    /** Must atomically check usage and create an idempotent reservation. */
+    reserve(request: StorageQuotaReservationRequest): Promise<StorageQuotaReservation | StorageQuotaRejection>;
+    commit(request: StorageQuotaCommitRequest): Promise<StorageQuotaCommitResult>;
+    release(request: StorageQuotaReleaseRequest): Promise<StorageQuotaReleaseResult>;
+}>;
+export type StorageQuotaService = Readonly<{
+    reserve(request: StorageQuotaReservationRequest): Promise<StorageQuotaReservation>;
+    commit(request: StorageQuotaCommitRequest): Promise<StorageQuotaCommitResult>;
+    release(request: StorageQuotaReleaseRequest): Promise<StorageQuotaReleaseResult>;
+}>;
+/**
+ * Verified server-side identity for an attachment write.  It is intentionally
+ * richer than the generic quota adapter: attachment storage must be charged
+ * to one workspace, actor and immutable object key before a presign is issued.
+ */
+export type AttachmentStorageQuotaContext = Readonly<{
+    workspaceId: string;
+    actorUserId: string;
+    documentId: string;
+    storageKey: string;
+    proposedSize: number;
+    requestId: string;
+    idempotencyKey: string;
+    signal?: AbortSignal;
+}>;
+export type AttachmentStorageQuotaFinalization = Readonly<{
+    reservationId: string;
+    actualSize: number;
+}>;
+/**
+ * OSS invokes this only after it has verified tenant context and document
+ * access.  A host provider is never exposed to HTTP or browser code.
+ */
+export type AttachmentStorageQuotaAdmission = Readonly<{
+    reserve(context: AttachmentStorageQuotaContext): Promise<Readonly<{
+        id: string;
+    }>>;
+    finalize(context: AttachmentStorageQuotaContext, finalization: AttachmentStorageQuotaFinalization): Promise<void>;
+    releaseReservation(context: AttachmentStorageQuotaContext, reservationId: string): Promise<void>;
+    releaseCommitted(context: AttachmentStorageQuotaContext): Promise<void>;
+}>;
+export declare class MissingAttachmentStorageQuotaAdmissionError extends Error {
+    readonly code: "ATTACHMENT_STORAGE_QUOTA_ADMISSION_MISSING";
+    constructor();
+}
+export declare function requireAttachmentStorageQuotaAdmission(admission: AttachmentStorageQuotaAdmission | undefined): AttachmentStorageQuotaAdmission;
+export declare class StorageQuotaExceededError extends Error {
+    readonly code: "STORAGE_QUOTA_EXCEEDED";
+    readonly usageBytes: number;
+    readonly limitBytes: number;
+    readonly requestedBytes: number;
+    constructor(rejection: StorageQuotaRejection);
+}
+export declare function createStorageQuotaService(adapter: StorageQuotaAdapter): StorageQuotaService;