@classytic/arc 2.15.3 → 2.16.0

package/dist/integrations/mcp/index.mjs

@@ -1,6 +1,4 @@
-import { n as fieldRulesToZod, r as createMcpServer, t as resourceToTools } from "../../resourceToTools-tFYUNmM0.mjs";
-import { createHash, randomUUID } from "node:crypto";
-import fp from "fastify-plugin";
+import { a as defaultCrudDescription, c as mcpHandlerAdapter, d as toCallToolResult, f as toCallToolSuccess, i as fieldRulesToZod, l as permissionDeniedResult, m as createMcpServer, n as mcpPlugin, o as resolveCrudDescription, p as buildRequestContext, r as resourceToTools, s as invokeController, t as filterResourcesForMcp, u as toCallToolError } from "../../mcpPlugin-7vGV51ED.mjs";
 //#region src/integrations/mcp/defineTool.ts
 /**
 * Define a type-safe MCP tool.
@@ -186,528 +184,4 @@ function definePrompt(name, config) {
 	};
 }
 //#endregion
-//#region src/integrations/mcp/authBridge.ts
-/**
-* @classytic/arc — MCP Auth Bridge
-*
-* Resolves MCP session identity from request headers.
-* Supports three modes — the user chooses:
-*
-* 1. `false` — no auth, anonymous access
-* 2. `BetterAuthHandler` — OAuth 2.1 via Better Auth
-* 3. `McpAuthResolver` — custom function (API key, JWT, gateway headers, etc.)
-*/
-/** Distinguish BetterAuthHandler from McpAuthResolver */
-function isBetterAuth(auth) {
-	return typeof auth === "object" && auth !== null && "api" in auth && "handler" in auth;
-}
-/**
-* Resolve MCP session identity from request headers.
-*
-* @param headers - HTTP request headers
-* @param auth - false | BetterAuthHandler | McpAuthResolver
-* @param authCache - Optional short-lived cache to avoid redundant auth lookups
-*/
-async function resolveMcpAuth(headers, auth, authCache) {
-	if (auth === false) return null;
-	const cacheKey = authCache ? extractAuthCacheKey(headers) : null;
-	if (cacheKey && authCache) {
-		const cached = authCache.get(cacheKey);
-		if (cached !== void 0) return cached;
-	}
-	let result = null;
-	if (typeof auth === "function") try {
-		result = await auth(headers);
-	} catch {
-		result = null;
-	}
-	else if (isBetterAuth(auth)) try {
-		const session = await auth.api.getMcpSession({ headers });
-		if (!session?.userId) result = null;
-		else result = {
-			userId: session.userId,
-			organizationId: session.activeOrganizationId,
-			...session.clientId ? { clientId: session.clientId } : {},
-			...session.scopes ? { scopes: session.scopes.split(" ") } : {}
-		};
-	} catch {
-		result = null;
-	}
-	if (cacheKey && authCache) authCache.set(cacheKey, result);
-	return result;
-}
-const DEFAULT_AUTH_CACHE_TTL_MS = 5e3;
-const DEFAULT_AUTH_CACHE_MAX = 500;
-/** Short-lived auth cache to avoid redundant auth resolver calls in stateless mode */
-var McpAuthCache = class {
-	cache = /* @__PURE__ */ new Map();
-	ttlMs;
-	maxEntries;
-	constructor(opts) {
-		this.ttlMs = opts?.ttlMs ?? DEFAULT_AUTH_CACHE_TTL_MS;
-		this.maxEntries = opts?.maxEntries ?? DEFAULT_AUTH_CACHE_MAX;
-	}
-	get(key) {
-		const entry = this.cache.get(key);
-		if (!entry) return void 0;
-		if (Date.now() > entry.expires) {
-			this.cache.delete(key);
-			return;
-		}
-		return entry.result;
-	}
-	set(key, result) {
-		if (this.cache.size >= this.maxEntries) {
-			const now = Date.now();
-			for (const [k, v] of this.cache) if (now > v.expires) this.cache.delete(k);
-			if (this.cache.size >= this.maxEntries) {
-				const firstKey = this.cache.keys().next().value;
-				if (firstKey) this.cache.delete(firstKey);
-			}
-		}
-		this.cache.set(key, {
-			result,
-			expires: Date.now() + this.ttlMs
-		});
-	}
-};
-/**
-* Extract a cache key from auth-related headers.
-* Uses SHA-256 hash of header values to prevent cache key collisions
-* and avoid storing raw credentials in memory.
-*/
-function extractAuthCacheKey(headers) {
-	if (headers.authorization) return `authz:${hashForCache(headers.authorization)}`;
-	if (headers["x-api-key"]) return `apikey:${hashForCache(headers["x-api-key"])}`;
-	return null;
-}
-function hashForCache(value) {
-	return createHash("sha256").update(value).digest("hex").slice(0, 32);
-}
-/**
-* Register OAuth 2.1 discovery endpoints for MCP clients.
-* Only relevant when using Better Auth — custom auth doesn't need these.
-*/
-async function registerOAuthDiscovery(fastify, auth) {
-	fastify.get("/.well-known/oauth-authorization-server", async (req, reply) => {
-		await forwardResponse(reply, await auth.handler(toWebRequest(req)));
-	});
-	fastify.get("/.well-known/oauth-protected-resource", async (req, reply) => {
-		await forwardResponse(reply, await auth.handler(toWebRequest(req)));
-	});
-}
-function toWebRequest(req) {
-	const protocol = req.protocol ?? "http";
-	const host = req.hostname ?? "localhost";
-	return new Request(`${protocol}://${host}${req.url}`, {
-		method: req.method,
-		headers: req.headers
-	});
-}
-async function forwardResponse(reply, response) {
-	reply.status(response.status);
-	response.headers.forEach((value, key) => {
-		if (key.toLowerCase() !== "transfer-encoding") reply.header(key, value);
-	});
-	reply.send(await response.text());
-}
-//#endregion
-//#region src/integrations/mcp/schemaResources.ts
-/**
-* Register MCP Resources for schema discovery.
-*/
-function registerSchemaResources(server, resources, overrides) {
-	const srv = server;
-	srv.resource("schemas", "arc://schemas", {
-		title: "Arc Resource Schemas",
-		description: "All available resources",
-		mimeType: "application/json"
-	}, async () => ({ contents: [{
-		uri: "arc://schemas",
-		mimeType: "application/json",
-		text: JSON.stringify(resources.map((r) => ({
-			name: r.name,
-			displayName: r.displayName,
-			fieldCount: r.schemaOptions?.fieldRules ? Object.keys(r.schemaOptions.fieldRules).length : 0,
-			operations: getOps(r, overrides?.[r.name]?.operations),
-			presets: r._appliedPresets ?? []
-		})), null, 2)
-	}] }));
-	for (const r of resources) {
-		const uri = `arc://schemas/${r.name}`;
-		const schemaOpts = r.schemaOptions;
-		srv.resource(`schema-${r.name}`, uri, {
-			title: `${r.displayName} Schema`,
-			description: `Schema for ${r.displayName}`,
-			mimeType: "application/json"
-		}, async () => ({ contents: [{
-			uri,
-			mimeType: "application/json",
-			text: JSON.stringify({
-				name: r.name,
-				displayName: r.displayName,
-				operations: getOps(r, overrides?.[r.name]?.operations),
-				fields: r.schemaOptions?.fieldRules ?? {},
-				filterableFields: schemaOpts?.filterableFields ?? [],
-				presets: r._appliedPresets ?? []
-			}, null, 2)
-		}] }));
-	}
-}
-function getOps(r, override) {
-	let ops = [
-		"list",
-		"get",
-		"create",
-		"update",
-		"delete"
-	].filter((op) => !r.disabledRoutes?.includes(op));
-	if (override) ops = ops.filter((op) => override.includes(op));
-	return ops;
-}
-//#endregion
-//#region src/integrations/mcp/sessionCache.ts
-const DEFAULT_TTL_MS = 1800 * 1e3;
-const DEFAULT_MAX_SESSIONS = 1e3;
-var McpSessionCache = class {
-	sessions = /* @__PURE__ */ new Map();
-	ttlMs;
-	maxSessions;
-	cleanupTimer = null;
-	constructor(opts = {}) {
-		this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
-		this.maxSessions = opts.maxSessions ?? DEFAULT_MAX_SESSIONS;
-		if (this.ttlMs > 0) {
-			this.cleanupTimer = setInterval(() => this.cleanup(), Math.max(this.ttlMs / 2, 5e3));
-			if (this.cleanupTimer.unref) this.cleanupTimer.unref();
-		}
-	}
-	/** Get an existing session by ID */
-	get(sessionId) {
-		const entry = this.sessions.get(sessionId);
-		if (!entry) return void 0;
-		if (Date.now() - entry.lastAccessed > this.ttlMs) {
-			this.remove(sessionId);
-			return;
-		}
-		return entry;
-	}
-	/** Store a new session */
-	set(sessionId, entry) {
-		if (this.sessions.size >= this.maxSessions && !this.sessions.has(sessionId)) this.evictOldest();
-		entry.lastAccessed = Date.now();
-		this.sessions.set(sessionId, entry);
-	}
-	/** Refresh the TTL on a session */
-	touch(sessionId) {
-		const entry = this.sessions.get(sessionId);
-		if (entry) entry.lastAccessed = Date.now();
-	}
-	/** Remove and close a session */
-	remove(sessionId) {
-		const entry = this.sessions.get(sessionId);
-		if (entry) {
-			this.closeTransport(entry);
-			this.sessions.delete(sessionId);
-		}
-	}
-	/** Remove all expired sessions */
-	cleanup() {
-		const now = Date.now();
-		for (const [id, entry] of this.sessions) if (now - entry.lastAccessed > this.ttlMs) {
-			this.closeTransport(entry);
-			this.sessions.delete(id);
-		}
-	}
-	/** Close all sessions and stop cleanup timer */
-	close() {
-		if (this.cleanupTimer) {
-			clearInterval(this.cleanupTimer);
-			this.cleanupTimer = null;
-		}
-		for (const [id, entry] of this.sessions) {
-			this.closeTransport(entry);
-			this.sessions.delete(id);
-		}
-	}
-	/** Current session count */
-	get size() {
-		return this.sessions.size;
-	}
-	/** Evict the oldest (least recently accessed) session */
-	evictOldest() {
-		let oldestId = null;
-		let oldestTime = Infinity;
-		for (const [id, entry] of this.sessions) if (entry.lastAccessed < oldestTime) {
-			oldestTime = entry.lastAccessed;
-			oldestId = id;
-		}
-		if (oldestId) this.remove(oldestId);
-	}
-	/** Safely close a transport */
-	closeTransport(entry) {
-		try {
-			const transport = entry.transport;
-			if (transport && typeof transport.close === "function") transport.close();
-		} catch {}
-	}
-};
-//#endregion
-//#region src/integrations/mcp/mcpPlugin.ts
-/**
-* @classytic/arc — MCP Plugin (Level 1)
-*
-* Fastify plugin that auto-generates MCP tools from Arc resources.
-*
-* Two transport modes:
-* - **Stateless** (default) — fresh server per request, no session tracking.
-*   Best for production, horizontal scaling, serverless, edge.
-* - **Stateful** — sessions cached with TTL, reused across requests.
-*   Use when you need server-initiated notifications or long-lived connections.
-*
-* Auth is NOT enforced — the plugin respects whatever auth mode you choose:
-* - `auth: false` — no auth, anonymous access (dev/testing/stdio)
-* - `auth: betterAuthInstance` — OAuth 2.1 via Better Auth's mcp() plugin
-* - `auth: async (headers) => {...}` — custom function (API key, JWT, gateway, etc.)
-*
-* @example
-* ```typescript
-* // Stateless (default) — production, scalable
-* await app.register(mcpPlugin, { resources, auth: false });
-*
-* // Stateful — when you need session persistence
-* await app.register(mcpPlugin, { resources, stateful: true, sessionTtlMs: 600000 });
-*
-* // Multiple MCP endpoints scoped to different resource groups
-* await app.register(mcpPlugin, { resources: catalogResources, prefix: '/mcp/catalog' });
-* await app.register(mcpPlugin, { resources: orderResources, prefix: '/mcp/orders' });
-* ```
-*/
-const mcpPluginImpl = async (fastify, options) => {
-	let StreamableHTTPServerTransport;
-	try {
-		StreamableHTTPServerTransport = (await import("@modelcontextprotocol/sdk/server/streamableHttp.js")).StreamableHTTPServerTransport;
-	} catch {
-		throw new Error("@modelcontextprotocol/sdk is required for MCP support. Install it: npm install @modelcontextprotocol/sdk");
-	}
-	try {
-		await import("zod");
-	} catch {
-		throw new Error("zod is required for MCP tool schemas. Install it: npm install zod");
-	}
-	let enabledResources;
-	if (options.include) {
-		const includeSet = new Set(options.include);
-		enabledResources = options.resources.filter((r) => includeSet.has(r.name));
-	} else {
-		const excludeSet = new Set(options.exclude ?? []);
-		enabledResources = options.resources.filter((r) => !excludeSet.has(r.name));
-	}
-	const overrides = options.overrides ?? {};
-	const allTools = enabledResources.flatMap((r) => {
-		const resOverrides = overrides[r.name] ?? {};
-		return resourceToTools(r, {
-			...resOverrides,
-			toolNamePrefix: resOverrides.toolNamePrefix ?? options.toolNamePrefix
-		});
-	});
-	if (options.extraTools) allTools.push(...options.extraTools);
-	fastify.log.info(`mcpPlugin: ${allTools.length} tools from ${enabledResources.length} resources`);
-	const overrideOpsMap = {};
-	for (const [name, cfg] of Object.entries(overrides)) overrideOpsMap[name] = { operations: cfg.operations };
-	const stateful = options.stateful === true;
-	const cache = stateful ? new McpSessionCache({
-		ttlMs: options.sessionTtlMs,
-		maxSessions: options.maxSessions
-	}) : null;
-	async function createServerInstance(authRef) {
-		const server = await createMcpServer({
-			name: options.serverName ?? "arc-mcp",
-			version: options.serverVersion ?? "1.0.0",
-			instructions: options.instructions,
-			tools: allTools,
-			prompts: options.extraPrompts
-		}, authRef);
-		registerSchemaResources(server, enabledResources, overrideOpsMap);
-		return server;
-	}
-	if (options.auth && isBetterAuth(options.auth)) await registerOAuthDiscovery(fastify, options.auth);
-	const prefix = options.prefix ?? "/mcp";
-	fastify.get(`${prefix}/health`, async (_request, reply) => {
-		reply.send({
-			status: "ok",
-			mode: stateful ? "stateful" : "stateless",
-			tools: allTools.length,
-			resources: enabledResources.length,
-			toolNames: allTools.map((t) => t.name),
-			sessions: cache?.size ?? null
-		});
-	});
-	if (stateful) registerStatefulRoutes(fastify, prefix, options, cache, createServerInstance, StreamableHTTPServerTransport);
-	else {
-		const authCache = options.auth && options.authCacheTtlMs !== 0 ? new McpAuthCache({ ttlMs: options.authCacheTtlMs }) : void 0;
-		registerStatelessRoutes(fastify, prefix, options, createServerInstance, StreamableHTTPServerTransport, authCache);
-	}
-	if (cache) fastify.addHook("onClose", async () => cache.close());
-	const registration = {
-		sessions: cache,
-		toolNames: allTools.map((t) => t.name),
-		resourceNames: enabledResources.map((r) => r.name),
-		stateful
-	};
-	if (!fastify.hasDecorator("mcp")) {
-		const registrations = /* @__PURE__ */ new Map();
-		registrations.set(prefix, registration);
-		const first = () => registrations.values().next().value;
-		const decorator = {
-			registrations,
-			get(p) {
-				return registrations.get(p);
-			},
-			get sessions() {
-				return first()?.sessions ?? null;
-			},
-			get toolNames() {
-				return first()?.toolNames ?? [];
-			},
-			get resourceNames() {
-				return first()?.resourceNames ?? [];
-			},
-			get stateful() {
-				return first()?.stateful ?? false;
-			}
-		};
-		fastify.decorate("mcp", decorator);
-	} else {
-		const existing = fastify.mcp;
-		if (existing) {
-			if (existing.registrations.has(prefix)) throw new Error(`mcpPlugin: prefix "${prefix}" is already registered`);
-			existing.registrations.set(prefix, registration);
-		}
-	}
-};
-function registerStatelessRoutes(fastify, prefix, options, createServer, Transport, authCache) {
-	fastify.post(prefix, async (request, reply) => {
-		const authResult = await resolveMcpAuth(request.headers, options.auth ?? false, authCache);
-		if (!authResult && options.auth) {
-			fastify.log.warn({
-				msg: "mcpPlugin: auth failed",
-				status: 401
-			});
-			return reply.code(401).send({
-				jsonrpc: "2.0",
-				error: {
-					code: -32e3,
-					message: "Unauthorized"
-				}
-			});
-		}
-		const authRef = { current: authResult };
-		const transport = new Transport({ sessionIdGenerator: void 0 });
-		await (await createServer(authRef)).connect(transport);
-		await transport.handleRequest(request.raw, reply.raw, request.body);
-	});
-	fastify.get(prefix, async (_request, reply) => {
-		reply.code(405).send({
-			jsonrpc: "2.0",
-			error: {
-				code: -32e3,
-				message: "SSE not available in stateless mode. Use stateful: true for server-initiated messages."
-			}
-		});
-	});
-	fastify.delete(prefix, async (_request, reply) => {
-		reply.code(200).send();
-	});
-}
-function registerStatefulRoutes(fastify, prefix, options, cache, createServer, Transport) {
-	/** Check if the requesting principal owns the session */
-	function isSessionOwner(entry, authResult) {
-		if (!options.auth || !entry.auth || !authResult) return true;
-		const prev = entry.auth;
-		return prev.userId === authResult.userId && prev.organizationId === authResult.organizationId && prev.clientId === authResult.clientId;
-	}
-	fastify.post(prefix, async (request, reply) => {
-		const authResult = await resolveMcpAuth(request.headers, options.auth ?? false);
-		if (!authResult && options.auth) {
-			fastify.log.warn({
-				msg: "mcpPlugin: auth failed",
-				status: 401
-			});
-			return reply.code(401).send({
-				jsonrpc: "2.0",
-				error: {
-					code: -32e3,
-					message: "Unauthorized"
-				}
-			});
-		}
-		const sessionId = request.headers["mcp-session-id"];
-		if (sessionId) {
-			const entry = cache.get(sessionId);
-			if (entry) {
-				if (!isSessionOwner(entry, authResult)) return reply.code(403).send({
-					jsonrpc: "2.0",
-					error: {
-						code: -32e3,
-						message: "Session ownership mismatch"
-					}
-				});
-				cache.touch(sessionId);
-				entry.auth = authResult;
-				entry.authRef.current = authResult;
-				await entry.transport.handleRequest(request.raw, reply.raw, request.body);
-				return;
-			}
-		}
-		const authRef = { current: authResult };
-		const transport = new Transport({
-			sessionIdGenerator: () => randomUUID(),
-			onsessioninitialized: (newSessionId) => {
-				cache.set(newSessionId, {
-					transport,
-					lastAccessed: Date.now(),
-					organizationId: authResult?.organizationId ?? "",
-					auth: authResult,
-					authRef
-				});
-			}
-		});
-		await (await createServer(authRef)).connect(transport);
-		await transport.handleRequest(request.raw, reply.raw, request.body);
-	});
-	fastify.get(prefix, async (request, reply) => {
-		const sessionId = request.headers["mcp-session-id"];
-		if (!sessionId) return reply.code(400).send({ error: "Missing Mcp-Session-Id header" });
-		const entry = cache.get(sessionId);
-		if (!entry) return reply.code(403).send({ error: "Unauthorized" });
-		if (options.auth) {
-			const authResult = await resolveMcpAuth(request.headers, options.auth);
-			if (!isSessionOwner(entry, authResult)) return reply.code(403).send({ error: "Unauthorized" });
-			entry.auth = authResult;
-			entry.authRef.current = authResult;
-		}
-		cache.touch(sessionId);
-		await entry.transport.handleRequest(request.raw, reply.raw);
-	});
-	fastify.delete(prefix, async (request, reply) => {
-		const sessionId = request.headers["mcp-session-id"];
-		if (!sessionId) return reply.code(400).send({ error: "Missing Mcp-Session-Id header" });
-		const entry = cache.get(sessionId);
-		if (!entry) return reply.code(204).send();
-		if (options.auth) {
-			const authResult = await resolveMcpAuth(request.headers, options.auth);
-			if (!isSessionOwner(entry, authResult)) return reply.code(403).send({ error: "Unauthorized" });
-			entry.auth = authResult;
-			entry.authRef.current = authResult;
-		}
-		cache.remove(sessionId);
-		reply.code(204).send();
-	});
-}
-const mcpPlugin = fp(mcpPluginImpl, {
-	name: "arc-mcp",
-	fastify: "5.x"
-});
-//#endregion
-export { bridgeToMcp, buildMcpToolsFromBridges, createMcpServer, customGuard, definePrompt, defineTool, denied, fieldRulesToZod, getOrgId, getUserId, guard, hasOrg, isAuthenticated, isOrg, mcpPlugin, requireAuth, requireOrg, requireOrgId, requireRole, resourceToTools };
+export { bridgeToMcp, buildMcpToolsFromBridges, buildRequestContext, createMcpServer, customGuard, defaultCrudDescription, definePrompt, defineTool, denied, fieldRulesToZod, filterResourcesForMcp, getOrgId, getUserId, guard, hasOrg, invokeController, isAuthenticated, isOrg, mcpHandlerAdapter, mcpPlugin, permissionDeniedResult, requireAuth, requireOrg, requireOrgId, requireRole, resolveCrudDescription, resourceToTools, toCallToolError, toCallToolResult, toCallToolSuccess };

package/dist/integrations/mcp/testing.d.mts

@@ -1,9 +1,9 @@
-import { o as McpAuthResult, s as McpPluginOptions } from "../../types-BQsjgQzS.mjs";
+import { c as McpAuthResult, l as McpPluginOptions } from "../../types-BsJMEQ4D.mjs";
 
 //#region src/integrations/mcp/testing.d.ts
 interface TestMcpClientOptions {
   /** MCP plugin options (resources, overrides, etc.) — same as mcpPlugin config */
-  pluginOptions?: Pick<McpPluginOptions, "resources" | "overrides" | "include" | "exclude" | "toolNamePrefix" | "extraTools" | "extraPrompts" | "instructions">;
+  pluginOptions?: Pick<McpPluginOptions, "resources" | "overrides" | "expose" | "include" | "exclude" | "toolNamePrefix" | "extraTools" | "extraPrompts" | "instructions">;
   /** Auth identity for the test session */
   auth?: McpAuthResult | null;
   /** Server name (default: 'test-mcp') */

package/dist/integrations/mcp/testing.mjs

@@ -1,4 +1,4 @@
-import { r as createMcpServer, t as resourceToTools } from "../../resourceToTools-tFYUNmM0.mjs";
+import { m as createMcpServer, r as resourceToTools, t as filterResourcesForMcp } from "../../mcpPlugin-7vGV51ED.mjs";
 //#region src/integrations/mcp/testing.ts
 /**
 * @classytic/arc/mcp/testing — MCP Test Utilities
@@ -52,15 +52,11 @@ async function createTestMcpClient(options = {}) {
 	const auth = options.auth ?? { userId: "test-user" };
 	const serverName = options.serverName ?? "test-mcp";
 	const overrides = pluginOpts.overrides ?? {};
-	let enabledResources = pluginOpts.resources ?? [];
-	if (pluginOpts.include) {
-		const includeSet = new Set(pluginOpts.include);
-		enabledResources = enabledResources.filter((r) => includeSet.has(r.name));
-	} else if (pluginOpts.exclude) {
-		const excludeSet = new Set(pluginOpts.exclude);
-		enabledResources = enabledResources.filter((r) => !excludeSet.has(r.name));
-	}
-	const tools = enabledResources.flatMap((r) => {
+	const tools = filterResourcesForMcp(pluginOpts.resources ?? [], {
+		expose: pluginOpts.expose,
+		include: pluginOpts.include,
+		exclude: pluginOpts.exclude
+	}).flatMap((r) => {
 		const resOverrides = overrides[r.name] ?? {};
 		return resourceToTools(r, {
 			...resOverrides,

package/dist/integrations/streamline.d.mts

@@ -50,7 +50,40 @@ interface WorkflowLike {
     }; /** Repository — used by the list-runs endpoint to query workflow_runs. */
     repository?: {
       getAll(params: Record<string, unknown>, options?: Record<string, unknown>): Promise<unknown>;
+      /**
+       * Tenant-scoped lookup by id. Used by the DELETE handler for a
+       * defense-in-depth pre-flight: streamline 2.3.3's `wf.get(runId)` /
+       * `engine.get` does NOT accept tenant options, so a cross-tenant
+       * runId can leak data through the engine path. Going through the
+       * repository here means mongokit's tenant-filter plugin scopes the
+       * read — cross-tenant requests get a clean 404 and DELETEs only
+       * touch rows the caller actually owns.
+       */
+      getById?(id: string, options?: Record<string, unknown>): Promise<WorkflowRunLike | null>;
+      /**
+       * Hard-delete a run by id. Routed through mongokit's inherited
+       * `Repository.delete()` so multi-tenant scope + audit/cache plugins
+       * fire. Wired into `DELETE /:workflowId/runs/:runId` — operator
+       * escape hatch for dead-lettered or stuck rows.
+       */
+      delete?(id: string, options?: Record<string, unknown>): Promise<unknown>;
     };
+    /**
+     * Streamline >= 2.3.2 — explicit deploy-time index sync (TTL on
+     * terminal runs + tenant compounds). When the host configured
+     * `createContainer({ retention })`, arc's app-level deploy hook
+     * should call `await container.syncRetentionIndexes()` after
+     * `mongoose.connect`. Optional so older streamline versions
+     * (and partial mocks) still satisfy the structural shape.
+     */
+    syncRetentionIndexes?: () => Promise<void>;
+    /**
+     * Streamline >= 2.3.2 — stop background sweepers and release timers.
+     * Arc's `onClose` hook below calls this on every workflow's container
+     * during graceful shutdown so SIGTERM doesn't leave the stale-run
+     * sweeper running. Optional + idempotent.
+     */
+    dispose?: () => void;
   };
 }
 interface WorkflowRunLike {
@@ -67,7 +100,36 @@ interface WorkflowRunLike {
   stepLogs?: unknown[];
   createdAt?: Date;
   updatedAt?: Date;
+  /**
+   * Streamline >= 2.3.3 — pinned definition version (semver) the run
+   * started under. Hosts surfacing a "stuck on old version" UI read this
+   * to decide whether to nudge a migration. Optional for back-compat
+   * with runs created before 2.3.3.
+   */
+  definitionVersion?: string;
+  /**
+   * Streamline >= 2.3.3 — count of stale-recovery / sweeper transitions
+   * applied to this run. Sweeper dead-letters once this hits
+   * `RetentionOptions.maxStaleRecoveries`; UIs can highlight runs trending
+   * toward dead-letter.
+   */
+  recoveryAttempts?: number;
 }
+/**
+ * Streamline >= 2.3.3 dead-letter discriminator. The run.status stays
+ * `'failed'`; the discrimination is `error.code`:
+ *   - `'stale_heartbeat'` — sweeper terminated; transient crash signal.
+ *   - `'dead_lettered'`   — exceeded `maxStaleRecoveries`; permanent.
+ *   - `'VERSION_MISMATCH'` — engine deployed a step graph the run can't
+ *     resume against; admin must rewind / migrate / cancel.
+ *
+ * Hosts switch on `error.code` for dashboards / alerting.
+ */
+declare const STREAMLINE_FAILURE_CODES: {
+  readonly STALE_HEARTBEAT: "stale_heartbeat";
+  readonly DEAD_LETTERED: "dead_lettered";
+  readonly VERSION_MISMATCH: "VERSION_MISMATCH";
+};
 interface StreamlinePluginOptions {
   /** Array of workflows created with createWorkflow() */
   workflows: WorkflowLike[];
@@ -176,7 +238,14 @@ declare const STREAMLINE_BUS_EVENTS: readonly ["step:started", "step:completed",
  * the run is still active after them.
  */
 declare const STREAMLINE_TERMINAL_EVENTS: readonly ["workflow:completed", "workflow:failed", "workflow:cancelled"];
-/** Pluggable streamline integration for Arc */
+/**
+ * Pluggable streamline integration for Arc.
+ *
+ * Wrapped in `fastify-plugin` so Fastify treats `options.prefix` as a
+ * plain plugin option (NOT an encapsulation prefix). Without the wrapper,
+ * Fastify would prepend `options.prefix` to every route, then the plugin
+ * code would prepend it again — the duplicate-prefix bug.
+ */
 declare const streamlinePlugin: FastifyPluginAsync<StreamlinePluginOptions>;
 //#endregion
-export { STREAMLINE_BUS_EVENTS, STREAMLINE_TERMINAL_EVENTS, StreamlinePluginOptions, WorkflowLike, WorkflowRunLike, WorkflowStartOptions, streamlinePlugin };
+export { STREAMLINE_BUS_EVENTS, STREAMLINE_FAILURE_CODES, STREAMLINE_TERMINAL_EVENTS, StreamlinePluginOptions, WorkflowLike, WorkflowRunLike, WorkflowStartOptions, streamlinePlugin };