@selvajs/server 0.2.0-beta.1

package/src/definitions/index.ts

@@ -0,0 +1,22 @@
+// Definitions server slice — the write orchestration (DefinitionService), the
+// compute-schema extraction/validation gate, and the render loader. All
+// composition-root wiring (stores, warm-client cache, server resolution) is
+// injected; access gating stays with the calling app.
+
+export { DefinitionService, type CreateDefinitionRecord } from './definition-service.js';
+
+export {
+	fetchSchemaFromCompute,
+	assertSupportedSchemaVersion,
+	SchemaExtractionError
+} from './schema-extraction.js';
+
+export {
+	createDefinitionLoader,
+	DefinitionLoadError,
+	type DefinitionChannel,
+	type DefinitionLoader,
+	type DefinitionLoaderDeps,
+	type DefinitionLoadErrorKind,
+	type LoadedDefinition
+} from './load-for-render.js';

package/src/definitions/load-for-render.ts

@@ -0,0 +1,272 @@
+// Loader for "given a definition record, produce everything the client needs to
+// render its form and solve it": version resolution, blob fetch, compute-server
+// resolution, schema fetch (with the ADR 0005 staleness check), default merging.
+//
+// Access gating is intentionally NOT done here — the calling route decides
+// whether `ctx` is allowed to load this definition, since gates differ across
+// routes (project membership, segment ownership, share-token, admin override).
+//
+// Everything stateful is injected (`DefinitionLoaderDeps`): stores, server
+// resolution, the warm-client cache, and the schema fetcher — so any app built
+// on the engine can wire its own composition root.
+
+import type { GrasshopperClient } from '@selvajs/compute/grasshopper';
+import { UI_SCHEMA_VERSION, type UISchema } from '@selvajs/schemas';
+import type {
+	ComputeServerConfig,
+	DefinitionRecord,
+	DefinitionVersion,
+	IDefinitionStore,
+	IProjectStore,
+	IStorageProvider,
+	RequestContext
+} from '@selvajs/platform';
+import { fetchSchemaFromCompute } from './schema-extraction.js';
+
+export type DefinitionChannel = 'live' | 'draft';
+
+export interface LoadedDefinition {
+	version: DefinitionVersion;
+	definitionSource: Uint8Array;
+	computeServer: ComputeServerConfig;
+	schema: UISchema;
+}
+
+/**
+ * Classified failure modes so callers can map to appropriate HTTP status:
+ *   - 'data':           record references a version/blob that isn't there. (400)
+ *   - 'missing-config': no compute server resolvable for this org/definition. (503)
+ *   - 'connect':        compute server is configured but unreachable. (503)
+ *   - 'schema':         compute responded but IO/schema phase failed. (500)
+ */
+export type DefinitionLoadErrorKind = 'data' | 'missing-config' | 'connect' | 'schema';
+
+export class DefinitionLoadError extends Error {
+	constructor(
+		public readonly kind: DefinitionLoadErrorKind,
+		message: string,
+		public readonly cause?: unknown
+	) {
+		super(message);
+		this.name = 'DefinitionLoadError';
+	}
+}
+
+export interface DefinitionLoaderDeps {
+	storage: Pick<IStorageProvider, 'get'>;
+	definitions: Pick<IDefinitionStore, 'getVersion' | 'setVersionSchema'>;
+	projects: Pick<IProjectStore, 'getProject'>;
+	/** §3 resolution order: definition pin → org default override → global default. */
+	resolveServer: (
+		ctx: RequestContext,
+		orgId: string | null,
+		opts: { definitionPin: string | null }
+	) => Promise<ComputeServerConfig>;
+	/** Shared warm-client cache (ADR 0004: keyed by server id, definition-guid affinity header). */
+	getClient: (
+		server: ComputeServerConfig,
+		opts: { definitionGuid: string }
+	) => Promise<{ client: GrasshopperClient }>;
+	/** Schema extraction; defaults to `fetchSchemaFromCompute`. Injectable for tests. */
+	fetchSchema?: (bytes: Uint8Array, server: ComputeServerConfig) => Promise<UISchema>;
+	/**
+	 * Verbose IO diagnostics — when set, an unhealthy IO result (empty inputs /
+	 * parse / load errors) also dumps the raw /io wire shape so
+	 * casing/serialization mismatches are visible.
+	 */
+	computeDebug?: boolean;
+	/** Diagnostic sink; defaults to `console.warn`. */
+	onWarn?: (message: string, detail?: string) => void;
+}
+
+export type DefinitionLoader = (
+	ctx: RequestContext,
+	record: DefinitionRecord,
+	channel: DefinitionChannel,
+	explicitVersionId?: string | null
+) => Promise<LoadedDefinition>;
+
+/**
+ * Build a definition loader over the injected stores/compute wiring.
+ *
+ * The returned function loads a definition's version blob + schema (with
+ * merged compute defaults). By default it resolves the `channel` pointer
+ * (live/draft); pass `explicitVersionId` to render an arbitrary historical
+ * version instead — the caller must gate that behind edit permission
+ * (editor-only, like the draft channel). Throws `DefinitionLoadError` for
+ * classified failures so the caller can translate to HTTP status codes.
+ */
+export function createDefinitionLoader(deps: DefinitionLoaderDeps): DefinitionLoader {
+	const {
+		storage,
+		definitions,
+		projects,
+		resolveServer,
+		getClient,
+		fetchSchema = fetchSchemaFromCompute,
+		computeDebug = false,
+		onWarn = (message, detail) => (detail ? console.warn(message, detail) : console.warn(message))
+	} = deps;
+
+	return async function loadDefinitionForRender(ctx, record, channel, explicitVersionId) {
+		const versionId =
+			explicitVersionId ?? (channel === 'draft' ? record.draftVersionId : record.liveVersionId);
+		if (!versionId)
+			throw new DefinitionLoadError(
+				'data',
+				`Definition '${record.guid}' has no ${channel} version`
+			);
+
+		const version = await definitions.getVersion(ctx, versionId);
+		if (!version) throw new DefinitionLoadError('data', `version missing for '${record.guid}'`);
+		// An explicitly requested version must belong to this definition.
+		if (version.definitionId !== record.guid)
+			throw new DefinitionLoadError('data', `version does not belong to '${record.guid}'`);
+
+		const definitionSource = await storage.get(version.fileKey);
+		if (!definitionSource)
+			throw new DefinitionLoadError(
+				'data',
+				`Definition file for '${record.guid}' not found on disk`
+			);
+
+		const project = await projects.getProject(ctx, record.projectId);
+		let computeServer: ComputeServerConfig;
+		try {
+			computeServer = await resolveServer(ctx, project?.orgId ?? null, {
+				definitionPin: record.computeServerId ?? null
+			});
+		} catch (err) {
+			throw new DefinitionLoadError(
+				'missing-config',
+				'No compute server configured for this definition',
+				err
+			);
+		}
+
+		// Only the client is used here (getIO); the entry's solve scheduler rides
+		// along unused.
+		let client: GrasshopperClient;
+		try {
+			client = (await getClient(computeServer, { definitionGuid: record.guid })).client;
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			throw new DefinitionLoadError(
+				'connect',
+				`Failed to connect to Rhino Compute server: ${message}`,
+				err
+			);
+		}
+
+		try {
+			// Prefer the schema cached on the version row (extracted + validated at
+			// upload) — but ONLY when its format version matches the app's. The
+			// stored schema is a disposable cache (ADR 0005): on a version mismatch
+			// (or a pre-caching row with no schema at all) re-extract from compute,
+			// whose C# SchemaMigrator emits the current format — the web side never
+			// migrates schemas itself. `getIO` is always needed to merge compute
+			// default values into the schema, cached or not.
+			const cachedSchema = version.schema as UISchema | undefined;
+			const freshCache =
+				cachedSchema && cachedSchema.schemaVersion === UI_SCHEMA_VERSION ? cachedSchema : null;
+			const [definition, fetchedSchema] = await Promise.all([
+				client.getIO(definitionSource),
+				freshCache ? Promise.resolve(freshCache) : fetchSchema(definitionSource, computeServer)
+			]);
+
+			// Persist the refreshed schema back onto the version row (best-effort —
+			// a viewer context may lack write access; the next editor render or the
+			// solve-time backfill will land it). Only when the re-extracted schema
+			// is at the app's current version: persisting an older format (compute
+			// plugin behind the app) would just go stale again next render.
+			if (!freshCache && fetchedSchema.schemaVersion === UI_SCHEMA_VERSION) {
+				definitions.setVersionSchema(ctx, version.id, fetchedSchema).catch((err) => {
+					onWarn(
+						`[loadForRender] schema cache refresh failed for version ${version.id}: ` +
+							`${err instanceof Error ? err.message : String(err)}`
+					);
+				});
+			}
+
+			if (!definition) {
+				throw new Error(`Failed to get definition IO — server returned undefined`);
+			}
+
+			// Surface IO health when something looks off: zero inputs, or the compute
+			// layer reported parse/load problems (e.g. an empty ValueList because its
+			// backing GH component didn't resolve → "Missing Definition Objects", or a
+			// PascalCase /io response the parser silently dropped to []). On a problem
+			// we also fetch the raw IO so the un-parsed wire shape is in the logs.
+			// Always-on warn (cheap, only fires on the unhappy path); the verbose raw
+			// dump is gated on `computeDebug`.
+			const ioParseErrors = (definition as { parseErrors?: unknown[] }).parseErrors ?? [];
+			const ioLoadErrors = (definition as { loadErrors?: unknown[] }).loadErrors ?? [];
+			const ioLooksBroken =
+				definition.inputs.length === 0 || ioParseErrors.length > 0 || ioLoadErrors.length > 0;
+			if (ioLooksBroken) {
+				onWarn(
+					`[loadForRender] IO health for '${record.guid}':`,
+					JSON.stringify({
+						inputCount: definition.inputs.length,
+						outputCount: definition.outputs?.length,
+						parseErrors: ioParseErrors,
+						loadErrors: ioLoadErrors,
+						loadWarnings: (definition as { loadWarnings?: unknown }).loadWarnings
+					})
+				);
+				if (computeDebug) {
+					const rawIO = await client
+						.getRawIO(definitionSource)
+						.catch((e) => ({ error: String(e) }));
+					onWarn('[loadForRender] raw /io:', JSON.stringify(rawIO).slice(0, 3000));
+				}
+			}
+
+			return {
+				version,
+				definitionSource,
+				computeServer,
+				schema: mergeComputeDefaults(fetchedSchema, definition.inputs)
+			};
+		} catch (err) {
+			if (err instanceof DefinitionLoadError) throw err;
+			const message = err instanceof Error ? err.message : String(err);
+			throw new DefinitionLoadError('schema', message, err);
+		}
+	};
+}
+
+// Merge default values from Compute definition into schema inputs.
+// Colors come back as "r,g,b" or "a,r,g,b" strings — convert to hex so the
+// color picker can consume them directly.
+function mergeComputeDefaults(
+	schema: UISchema,
+	computeInputs: Array<{ id?: string; paramType?: string; default?: unknown }>
+): UISchema {
+	const byParamId = new Map(computeInputs.map((input) => [input.id, input]));
+
+	return {
+		...schema,
+		inputs: schema.inputs.map((schemaInput) => {
+			const computeInput = byParamId.get(schemaInput.id);
+
+			if (computeInput?.paramType === 'Color' && computeInput.default !== undefined) {
+				const toHex = (value: number) => value.toString(16).padStart(2, '0');
+				const parts = String(computeInput.default)
+					.split(',')
+					.map((s) => parseInt(s.trim(), 10));
+
+				if (parts.length === 3) {
+					computeInput.default = `#${toHex(parts[0])}${toHex(parts[1])}${toHex(parts[2])}`;
+				} else if (parts.length === 4) {
+					computeInput.default = `#${toHex(parts[1])}${toHex(parts[2])}${toHex(parts[3])}`;
+				}
+			}
+
+			if (computeInput && computeInput.default !== undefined) {
+				return { ...schemaInput, default: computeInput.default };
+			}
+			return schemaInput;
+		})
+	};
+}

package/src/definitions/schema-extraction.ts

@@ -0,0 +1,117 @@
+// Shared compute-schema extraction. One implementation used by:
+//   - upload routes (validate-and-cache gate — no upload without a valid schema)
+//   - the render path (falls back to live extraction for un-cached or stale
+//     versions; see load-for-render.ts and ADR 0005)
+//   - the temporary solve-time backfill bridge (see the app's specs/SchemaCaching.md)
+//
+// Extraction IS validation: a `.gh` with no valid "Schema" output, or an
+// unreachable compute server, throws here and the caller rejects the upload.
+
+import { camelcaseKeys } from '@selvajs/compute/core';
+import { UI_SCHEMA_VERSION, type UISchema } from '@selvajs/schemas';
+import type { ComputeServerConfig } from '@selvajs/platform';
+
+/** Thrown when compute is reachable but the definition yields no usable schema. */
+export class SchemaExtractionError extends Error {
+	constructor(
+		public readonly kind: 'unreachable' | 'invalid' | 'unsupported',
+		message: string
+	) {
+		super(message);
+		this.name = 'SchemaExtractionError';
+	}
+}
+
+function parseSemver(version: string): [number, number, number] | null {
+	const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
+	return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+/**
+ * Plugin↔app compat gate: reject a schema emitted by a NEWER plugin than this
+ * app was built against — its shape may contain constructs the renderer does
+ * not know. Older (or missing) versions pass: the compute-side C# migrator
+ * always emits its own current version, and an older shape only lacks
+ * optional additions.
+ */
+export function assertSupportedSchemaVersion(schema: UISchema): void {
+	const version = schema.schemaVersion;
+	if (!version) return; // pre-2.12.0 plugin — older than the app, fine
+	const extracted = parseSemver(version);
+	const supported = parseSemver(UI_SCHEMA_VERSION);
+	if (!extracted || !supported) return;
+	const newer =
+		extracted[0] > supported[0] ||
+		(extracted[0] === supported[0] &&
+			(extracted[1] > supported[1] ||
+				(extracted[1] === supported[1] && extracted[2] > supported[2])));
+	if (newer) {
+		throw new SchemaExtractionError(
+			'unsupported',
+			`This definition was authored with a newer Selva plugin (schema format ${version}); ` +
+				`this server supports schema format ≤ ${UI_SCHEMA_VERSION}. Update the server, or ` +
+				`re-save the definition with a matching plugin version.`
+		);
+	}
+}
+
+/**
+ * Fetch the UI schema from Rhino Compute's `/grasshopper/schema` endpoint (no
+ * solve required). Throws `SchemaExtractionError` so callers can map to the
+ * right HTTP status (503 unreachable / 422 invalid or unsupported).
+ */
+export async function fetchSchemaFromCompute(
+	definitionBytes: Uint8Array,
+	server: ComputeServerConfig
+): Promise<UISchema> {
+	const schemaUrl = new URL('/grasshopper/schema', server.serverUrl).toString();
+
+	const formData = new FormData();
+	const blob = new Blob([new Uint8Array(definitionBytes)], { type: 'application/octet-stream' });
+	formData.append('file', blob, 'definition.gh');
+
+	const headers: Record<string, string> = {};
+	if (server.apiKey) {
+		headers['RhinoComputeKey'] = server.apiKey;
+	}
+
+	let response: Response;
+	try {
+		response = await fetch(schemaUrl, { method: 'POST', headers, body: formData });
+	} catch (err) {
+		throw new SchemaExtractionError(
+			'unreachable',
+			`Compute server is unreachable: ${err instanceof Error ? err.message : String(err)}`
+		);
+	}
+
+	if (!response.ok) {
+		throw new SchemaExtractionError(
+			'unreachable',
+			`Schema endpoint returned ${response.status}: ${response.statusText}`
+		);
+	}
+
+	// Compute returns [{ FileName, Schemas }] with PascalCase wrapper keys only.
+	// The schema contents are already camelCase from our C# serializer, so we only
+	// need a shallow camelcase per wrapper to normalize FileName→fileName,
+	// Schemas→schemas (shallow camelcaseKeys is a no-op on arrays, so each
+	// element is normalized individually). deep:true would mangle user-defined
+	// option names (e.g. "Display3d" → "display3d").
+	const raw = await response.json();
+	const results = (Array.isArray(raw) ? raw : [raw]).map((r) => camelcaseKeys(r)) as {
+		schemas: UISchema[];
+	}[];
+	const schemas = results.flatMap((r) => r.schemas ?? []);
+
+	if (schemas.length === 0) {
+		throw new SchemaExtractionError(
+			'invalid',
+			'No schemas found in definition.\n\n' +
+				'In Grasshopper, verify a Context Bake component with the output name "Schema" is present and wired to the solver.'
+		);
+	}
+
+	assertSupportedSchemaVersion(schemas[0]);
+	return schemas[0];
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * `@selvajs/server` — transport-agnostic compute/solve server building blocks
+ * for apps built on the Selva engine.
+ *
+ * The compute stack (limits, per-key rate limiting, SSRF guard, input
+ * transform) that used to live inside the `@selvajs/selva` app, extracted so a
+ * consuming app can reuse it instead of copying it. Everything here is
+ * env-injected (no ambient `$env` / `process.env`) and framework-agnostic.
+ *
+ * The full compute subsurface is also available at `@selvajs/server/compute`,
+ * the definitions slice (DefinitionService, schema extraction/validation,
+ * render loader) at `@selvajs/server/definitions`, and the provider wiring
+ * (registry-driven `createSelvaProviders`) at `@selvajs/server/providers`.
+ */
+
+export * from './compute/index.js';
+export * from './definitions/index.js';
+export * from './providers/index.js';

package/src/providers/__tests__/create-selva-providers.test.ts

@@ -0,0 +1,172 @@
+/**
+ * Tests for `createSelvaProviders` (K5) — registry-driven provider selection,
+ * lazy memoized instantiation, config parsing (flags/branding/tenancy), the
+ * solve-metrics duck-type pick, and the external config-path override.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { fileURLToPath } from 'node:url';
+import type { IAuthProvider, IDataProvider, IStorageProvider } from '@selvajs/platform';
+import { createSelvaProviders, type ProviderRegistry } from '../create-selva-providers.js';
+
+class FakeData {}
+class FakeStorage {}
+
+function makeRegistry() {
+	const authLocal = vi.fn(() => ({ name: 'local-auth' }) as unknown as IAuthProvider);
+	const authSupabase = vi.fn(() => ({ name: 'supabase-auth' }) as unknown as IAuthProvider);
+	const dataLocal = vi.fn(() => new FakeData() as unknown as IDataProvider);
+	const dataSupabase = vi.fn(() => new FakeData() as unknown as IDataProvider);
+	const storageLocal = vi.fn(() => new FakeStorage() as unknown as IStorageProvider);
+	const registry: ProviderRegistry = {
+		auth: { local: authLocal, supabase: authSupabase },
+		data: { local: dataLocal, supabase: dataSupabase },
+		storage: { local: storageLocal }
+	};
+	return { registry, authLocal, authSupabase, dataLocal, dataSupabase, storageLocal };
+}
+
+const noBoot = { onBoot: () => {} };
+
+describe('registry selection', () => {
+	it('falls back to "local" for every slot when env is empty', async () => {
+		const { registry, authLocal, dataLocal, storageLocal } = makeRegistry();
+		const runtime = await createSelvaProviders({}, { registry, ...noBoot });
+		runtime.resolve();
+		expect(authLocal).toHaveBeenCalledTimes(1);
+		expect(dataLocal).toHaveBeenCalledTimes(1);
+		expect(storageLocal).toHaveBeenCalledTimes(1);
+	});
+
+	it('honors SELVA_*_PROVIDER env choices, case-insensitively', async () => {
+		const { registry, authSupabase, dataSupabase } = makeRegistry();
+		const runtime = await createSelvaProviders(
+			{ SELVA_AUTH_PROVIDER: 'Supabase', SELVA_DATA_PROVIDER: 'SUPABASE' },
+			{ registry, ...noBoot }
+		);
+		runtime.resolve();
+		expect(authSupabase).toHaveBeenCalledTimes(1);
+		expect(dataSupabase).toHaveBeenCalledTimes(1);
+	});
+
+	it('honors the defaults option over the built-in "local"', async () => {
+		const { registry, authSupabase } = makeRegistry();
+		const runtime = await createSelvaProviders(
+			{},
+			{ registry, defaults: { auth: 'supabase' }, ...noBoot }
+		);
+		runtime.resolve();
+		expect(authSupabase).toHaveBeenCalledTimes(1);
+	});
+
+	it('rejects an unknown choice, listing the registered names', async () => {
+		const { registry } = makeRegistry();
+		const runtime = await createSelvaProviders(
+			{ SELVA_AUTH_PROVIDER: 'okta' },
+			{ registry, ...noBoot }
+		);
+		expect(() => runtime.resolve()).toThrow(/SELVA_AUTH_PROVIDER="okta".*local \| supabase/);
+	});
+});
+
+describe('laziness and memoization', () => {
+	it('does not instantiate providers until resolve() is called', async () => {
+		const { registry, authLocal } = makeRegistry();
+		await createSelvaProviders({}, { registry, ...noBoot });
+		expect(authLocal).not.toHaveBeenCalled();
+	});
+
+	it('instantiates once and logs the boot summary once across repeated resolves', async () => {
+		const { registry, authLocal } = makeRegistry();
+		const onBoot = vi.fn();
+		const runtime = await createSelvaProviders({}, { registry, onBoot });
+		runtime.resolve();
+		runtime.resolve();
+		runtime.flag('ENABLE_SHARING');
+		expect(authLocal).toHaveBeenCalledTimes(1);
+		expect(onBoot).toHaveBeenCalledTimes(1);
+		expect(onBoot.mock.calls[0][0]).toContain('auth=local-auth');
+		expect(onBoot.mock.calls[0][0]).toContain('data=FakeData');
+		expect(onBoot.mock.calls[0][0]).toContain('tenancy=single');
+	});
+});
+
+describe('config parsing', () => {
+	it('parses flags from SELVA_FLAG_* (omitted → false)', async () => {
+		const { registry } = makeRegistry();
+		const runtime = await createSelvaProviders(
+			{ SELVA_FLAG_ENABLE_SHARING: 'true', SELVA_FLAG_ALLOW_ORG_CREATION: 'no' },
+			{ registry, ...noBoot }
+		);
+		expect(runtime.flag('ENABLE_SHARING')).toBe(true);
+		expect(runtime.flag('ALLOW_ORG_CREATION')).toBe(false);
+		expect(runtime.flag('ALLOW_CROSS_ORG_PUBLIC')).toBe(false);
+	});
+
+	it('parses tenancy and rejects unknown values', async () => {
+		const { registry } = makeRegistry();
+		const multi = await createSelvaProviders({ SELVA_TENANCY: 'multi' }, { registry, ...noBoot });
+		expect(multi.tenancy()).toBe('multi');
+
+		const bad = await createSelvaProviders({ SELVA_TENANCY: 'galactic' }, { registry, ...noBoot });
+		expect(() => bad.tenancy()).toThrow(/SELVA_TENANCY="galactic"/);
+	});
+
+	it('brands with defaults; copyright falls back to the overridden name', async () => {
+		const { registry } = makeRegistry();
+		const plain = await createSelvaProviders({}, { registry, ...noBoot });
+		expect(plain.branding().name).toBe('Selva');
+		expect(plain.branding().copyrightName).toBe('Selva');
+		expect(plain.branding().tagline).toBeTruthy();
+
+		const branded = await createSelvaProviders(
+			{ SELVA_BRAND_NAME: '  Acme  ' },
+			{ registry, ...noBoot }
+		);
+		expect(branded.branding().name).toBe('Acme');
+		expect(branded.branding().copyrightName).toBe('Acme');
+		expect(branded.branding().description).toContain('Acme');
+	});
+});
+
+describe('solve metric sink', () => {
+	it('falls back to a noop sink when the data provider has no solveMetrics', async () => {
+		const { registry } = makeRegistry();
+		const runtime = await createSelvaProviders({}, { registry, ...noBoot });
+		const sink = runtime.solveMetricSink();
+		expect(typeof sink.record).toBe('function');
+		expect(runtime.solveMetricSink()).toBe(sink); // memoized
+	});
+
+	it('reuses a duck-typed solveMetrics sink carried by the data provider', async () => {
+		const { registry } = makeRegistry();
+		const carried = { record: vi.fn() };
+		registry.data.local = vi.fn(() => ({ solveMetrics: carried }) as unknown as IDataProvider);
+		const runtime = await createSelvaProviders({}, { registry, ...noBoot });
+		expect(runtime.solveMetricSink()).toBe(carried);
+	});
+});
+
+describe('config-path override', () => {
+	it('loads the module default export and hands it the env', async () => {
+		const { registry, authLocal } = makeRegistry();
+		const configPath = fileURLToPath(new URL('./fixtures/override-config.mjs', import.meta.url));
+		const runtime = await createSelvaProviders(
+			{ OVERRIDE_MARKER: 'hello' },
+			{ registry, configPath, ...noBoot }
+		);
+		const config = runtime.resolve();
+		expect(config.auth.name).toBe('override-auth');
+		expect((config.data as unknown as { marker: string }).marker).toBe('hello');
+		expect(runtime.tenancy()).toBe('multi');
+		// The registry is bypassed entirely.
+		expect(authLocal).not.toHaveBeenCalled();
+	});
+
+	it('rejects at load time when the path does not exist', async () => {
+		const { registry } = makeRegistry();
+		await expect(
+			createSelvaProviders({}, { registry, configPath: './does-not-exist.js', ...noBoot })
+		).rejects.toThrow(/does-not-exist\.js/);
+	});
+});

package/src/providers/__tests__/fixtures/override-config.mjs

@@ -0,0 +1,8 @@
+// Fixture for the SELVA_CONFIG_PATH override test — a minimal selva.config.js
+// whose default export is a config factory, exactly as an operator would write.
+export default (env) => ({
+	tenancy: 'multi',
+	auth: { name: 'override-auth' },
+	data: { marker: env.OVERRIDE_MARKER },
+	storage: {}
+});