dsh-mnemon-source-memory-spaces 0.5.0-rc.1

package/lib/plugin-DlsNeZbQ.js

@@ -0,0 +1,388 @@
+import { a as digest, i as defineMemorySpaceProviderDefinition, o as requiredId } from "./definitions-DfmOqJjR.js";
+//#region src/providers/catalog.ts
+function memoryProviderDescriptor(id, catalog = []) {
+	const descriptor = catalog.find((candidate) => candidate.id === id);
+	if (descriptor === void 0) throw new Error(`unsupported memory provider: ${String(id)}`);
+	return descriptor;
+}
+function normalizeUrl(value, label) {
+	const normalized = value.trim().replace(/\/+$/u, "");
+	let url;
+	try {
+		url = new URL(normalized);
+	} catch {
+		throw new Error(`${label} must be a valid http(s) URL`);
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error(`${label} must use http or https`);
+	if (url.username !== "" || url.password !== "") throw new Error(`${label} must not contain credentials`);
+	return normalized;
+}
+function normalizeString(value, field) {
+	let normalized = typeof value === "string" ? value.trim() : value === void 0 || value === null ? "" : String(value).trim();
+	if (field.normalize === "trim-trailing-slash") normalized = normalized.replace(/\/+$/u, "");
+	const maximum = field.maxLength ?? (field.input === "secret" ? 8e3 : 2e3);
+	if (normalized.length > maximum) throw new Error(`${field.label} is too long (max ${maximum} characters)`);
+	if (field.required && normalized === "") throw new Error(`${field.label} is required`);
+	if (field.input === "url" && normalized !== "") return normalizeUrl(normalized, field.label);
+	if (field.options !== void 0 && normalized !== "" && !field.options.some((option) => option.value === normalized)) throw new Error(`${field.label} has an unsupported value`);
+	if (field.pattern !== void 0 && normalized !== "" && !new RegExp(field.pattern, "u").test(normalized)) throw new Error(field.validationMessage ?? `${field.label.charAt(0).toLowerCase()}${field.label.slice(1)} has an invalid format`);
+	return normalized;
+}
+function validateFieldBounds(field, value) {
+	if (field.min !== void 0 && field.max !== void 0 && (value < field.min || value > field.max)) throw new Error(`${field.label.charAt(0).toLowerCase()}${field.label.slice(1)} must be within ${field.min}..${field.max}`);
+	if (field.min !== void 0 && value < field.min) throw new Error(`${field.label} must be at least ${field.min}`);
+	if (field.max !== void 0 && value > field.max) throw new Error(`${field.label} must be at most ${field.max}`);
+}
+function normalizeScopedProviderConnection(providerId, scope, input, previous = {}, clearSecrets = [], catalog = []) {
+	const descriptor = memoryProviderDescriptor(providerId, catalog);
+	if ((descriptor.typeId ?? descriptor.id) === "mnemon-native") return {};
+	const fields = descriptor.fields.filter((item) => item.scope === scope);
+	const allowed = new Set(fields.map((item) => item.key));
+	for (const key of Object.keys(input ?? {})) if (!allowed.has(key)) throw new Error(`unsupported ${descriptor.label} ${scope} setting: ${key}`);
+	for (const key of clearSecrets) if (fields.find((item) => item.key === key)?.input !== "secret") throw new Error(`cannot clear non-secret ${descriptor.label} ${scope} setting: ${key}`);
+	const output = {};
+	for (const configField of fields) {
+		if (clearSecrets.includes(configField.key)) {
+			output[configField.key] = "";
+			continue;
+		}
+		const value = input?.[configField.key] ?? previous[configField.key] ?? configField.defaultValue;
+		if (configField.input === "boolean") {
+			if (value === void 0) continue;
+			if (typeof value === "boolean") output[configField.key] = value;
+			else if (value === "true" || value === "false") output[configField.key] = value === "true";
+			else throw new Error(`${configField.label} must be true or false`);
+			continue;
+		}
+		if (configField.input === "number") {
+			if (value === void 0 || value === "") continue;
+			const parsed = typeof value === "number" ? value : Number(value);
+			if (!Number.isFinite(parsed)) throw new Error(`${configField.label} must be a finite number`);
+			validateFieldBounds(configField, parsed);
+			output[configField.key] = parsed;
+			continue;
+		}
+		const normalized = normalizeString(value, configField);
+		if (normalized !== "" || configField.required || configField.input === "secret") output[configField.key] = normalized;
+	}
+	return output;
+}
+function providerServiceFields(providerId, catalog = []) {
+	return memoryProviderDescriptor(providerId, catalog).fields.filter((field) => field.scope === "service");
+}
+function providerMemoryFields(providerId, catalog = []) {
+	return memoryProviderDescriptor(providerId, catalog).fields.filter((field) => field.scope === "memory");
+}
+function splitProviderConnection(providerId, connection, catalog = []) {
+	const serviceKeys = new Set(providerServiceFields(providerId, catalog).map((field) => field.key));
+	return {
+		service: Object.fromEntries(Object.entries(connection ?? {}).filter(([key]) => serviceKeys.has(key))),
+		memory: Object.fromEntries(Object.entries(connection ?? {}).filter(([key]) => !serviceKeys.has(key)))
+	};
+}
+function normalizeProviderServiceConnection(providerId, input, previous = {}, clearSecrets = [], catalog = []) {
+	return normalizeScopedProviderConnection(providerId, "service", input, previous, clearSecrets, catalog);
+}
+function normalizeProviderMemoryConnection(providerId, input, previous = {}, catalog = []) {
+	return normalizeScopedProviderConnection(providerId, "memory", input, previous, [], catalog);
+}
+function normalizeProviderConnection(providerId, input, previous = {}, clearSecrets = [], catalog = []) {
+	const descriptor = memoryProviderDescriptor(providerId, catalog);
+	if ((descriptor.typeId ?? descriptor.id) === "mnemon-native") return {};
+	const allowed = new Set(descriptor.fields.map((item) => item.key));
+	for (const key of Object.keys(input ?? {})) if (!allowed.has(key)) throw new Error(`unsupported ${descriptor.label} setting: ${key}`);
+	for (const key of clearSecrets) if (descriptor.fields.find((item) => item.key === key)?.input !== "secret") throw new Error(`cannot clear non-secret ${descriptor.label} setting: ${key}`);
+	const output = {};
+	for (const configField of descriptor.fields) {
+		if (clearSecrets.includes(configField.key)) {
+			output[configField.key] = "";
+			continue;
+		}
+		const supplied = input?.[configField.key];
+		const fallback = previous[configField.key] ?? configField.defaultValue;
+		const value = supplied ?? fallback;
+		if (configField.input === "boolean") {
+			if (value === void 0) continue;
+			if (typeof value === "boolean") output[configField.key] = value;
+			else if (value === "true" || value === "false") output[configField.key] = value === "true";
+			else throw new Error(`${configField.label} must be true or false`);
+			continue;
+		}
+		if (configField.input === "number") {
+			if (value === void 0 || value === "") continue;
+			const parsed = typeof value === "number" ? value : Number(value);
+			if (!Number.isFinite(parsed)) throw new Error(`${configField.label} must be a finite number`);
+			validateFieldBounds(configField, parsed);
+			output[configField.key] = parsed;
+			continue;
+		}
+		const normalized = normalizeString(value, configField);
+		if (normalized !== "" || configField.required || configField.input === "secret") output[configField.key] = normalized;
+	}
+	return output;
+}
+function publicScopedProviderConnection(providerId, scope, connection, catalog = []) {
+	const fields = memoryProviderDescriptor(providerId, catalog).fields.filter((item) => item.scope === scope);
+	const keys = new Set(fields.map((item) => item.key));
+	const secrets = new Set(fields.filter((item) => item.input === "secret").map((item) => item.key));
+	return {
+		settings: Object.fromEntries(Object.entries(connection).filter(([key]) => keys.has(key) && !secrets.has(key))),
+		configuredSecrets: [...secrets].filter((key) => String(connection[key] ?? "") !== "")
+	};
+}
+function publicProviderConnection(providerId, connection, catalog = []) {
+	const descriptor = memoryProviderDescriptor(providerId, catalog);
+	const secrets = new Set(descriptor.fields.filter((item) => item.input === "secret").map((item) => item.key));
+	return {
+		settings: Object.fromEntries(Object.entries(connection).filter(([key]) => !secrets.has(key))),
+		configuredSecrets: [...secrets].filter((key) => String(connection[key] ?? "") !== "")
+	};
+}
+/** Immutable descriptor/config normalizer scoped to one Provider snapshot. */
+var MemoryProviderCatalog = class {
+	providers;
+	constructor(providers) {
+		const ids = /* @__PURE__ */ new Set();
+		this.providers = Object.freeze(providers.map((provider) => {
+			if (ids.has(provider.id)) throw new Error(`memory provider descriptor is already registered: ${provider.id}`);
+			ids.add(provider.id);
+			return Object.freeze(structuredClone(provider));
+		}));
+	}
+	has(id) {
+		return typeof id === "string" && this.providers.some((provider) => provider.id === id);
+	}
+	descriptor(id) {
+		return memoryProviderDescriptor(id, this.providers);
+	}
+	serviceFields(id) {
+		return providerServiceFields(id, this.providers);
+	}
+	memoryFields(id) {
+		return providerMemoryFields(id, this.providers);
+	}
+	split(id, connection) {
+		return splitProviderConnection(id, connection, this.providers);
+	}
+	normalizeService(id, input, previous = {}, clearSecrets = []) {
+		return normalizeProviderServiceConnection(id, input, previous, clearSecrets, this.providers);
+	}
+	normalizeMemory(id, input, previous = {}) {
+		return normalizeProviderMemoryConnection(id, input, previous, this.providers);
+	}
+	normalize(id, input, previous = {}, clearSecrets = []) {
+		return normalizeProviderConnection(id, input, previous, clearSecrets, this.providers);
+	}
+	publicScoped(id, scope, connection) {
+		return publicScopedProviderConnection(id, scope, connection, this.providers);
+	}
+	public(id, connection) {
+		return publicProviderConnection(id, connection, this.providers);
+	}
+};
+const EMPTY_MEMORY_PROVIDER_CATALOG = new MemoryProviderCatalog([]);
+//#endregion
+//#region src/providers/registry.ts
+/** Lifecycle-owned factory directory used by Provider plugins and the Host. */
+var MemoryAdapterFactoryRegistry = class {
+	factories = /* @__PURE__ */ new Map();
+	constructor(factories = []) {
+		for (const factory of factories) this.register(factory);
+	}
+	register(factory) {
+		if (this.factories.has(factory.id)) throw new Error(`memory adapter factory is already registered: ${factory.id}`);
+		this.factories.set(factory.id, factory);
+		let active = true;
+		return () => {
+			if (!active) return;
+			active = false;
+			if (this.factories.get(factory.id) === factory) this.factories.delete(factory.id);
+		};
+	}
+	create(context) {
+		const adapters = /* @__PURE__ */ new Map();
+		for (const factory of this.factories.values()) {
+			const adapter = factory.create(context);
+			if (adapter.id !== factory.id) throw new Error(`memory adapter factory ${factory.id} returned ${adapter.id}`);
+			if (adapters.has(adapter.id)) throw new Error(`memory adapter is already created: ${adapter.id}`);
+			adapters.set(adapter.id, adapter);
+		}
+		return adapters;
+	}
+	ids() {
+		return [...this.factories.keys()];
+	}
+};
+var MemoryProviderAdapterRegistry = class extends MemoryAdapterFactoryRegistry {};
+//#endregion
+//#region src/providers/host.ts
+const SOURCE_INSTANCE_ID = /^[a-zA-Z0-9][a-zA-Z0-9._:/-]{0,299}$/u;
+function requiredSourceInstanceId(value) {
+	const normalized = value.trim();
+	if (!SOURCE_INSTANCE_ID.test(normalized)) throw new Error("Memory Spaces Source instanceId must start with a letter or digit and contain only letters, digits, ., _, :, / or -");
+	return normalized;
+}
+/** Presentation labels/icons do not change the semantic Generation digest. */
+function semanticManifest(manifest) {
+	return {
+		apiVersion: manifest.apiVersion,
+		kind: manifest.kind,
+		typeId: manifest.typeId,
+		packageName: manifest.packageName,
+		version: manifest.version,
+		origin: manifest.origin,
+		locality: manifest.locality,
+		workspaceBinding: manifest.workspaceBinding,
+		capabilities: manifest.capabilities,
+		fields: manifest.fields.map((field) => ({
+			key: field.key,
+			scope: field.scope,
+			role: field.role,
+			input: field.input,
+			required: field.required,
+			defaultValue: field.defaultValue,
+			min: field.min,
+			max: field.max,
+			maxLength: field.maxLength,
+			pattern: field.pattern,
+			normalize: field.normalize,
+			discoveryDefaultFrom: field.discoveryDefaultFrom,
+			options: field.options?.map((option) => option.value)
+		})),
+		secrets: manifest.secrets,
+		scoreSemantics: manifest.scoreSemantics
+	};
+}
+function assertRuntime(definition, adapter) {
+	const { manifest } = definition;
+	if (adapter.id !== manifest.typeId) throw new Error(`Memory Space Provider ${manifest.typeId} factory returned ${String(adapter.id)}`);
+	const requiredMethods = [
+		[manifest.capabilities.search, "search"],
+		[manifest.capabilities.browse, "list"],
+		[manifest.capabilities.graph, "graph"],
+		[manifest.capabilities.related, "related"],
+		[manifest.capabilities.remember, "remember"],
+		[manifest.capabilities.link, "link"],
+		[manifest.capabilities.forget, "forget"]
+	];
+	for (const [required, method] of requiredMethods) if (required && typeof adapter[method] !== "function") throw new Error(`Memory Space Provider ${manifest.typeId} declares ${String(method)} but its runtime does not implement it`);
+	if (manifest.scoreSemantics === "normalized-relevance" && adapter.scoreSemantics?.kind !== "normalized-relevance") throw new Error(`Memory Space Provider ${manifest.typeId} declares normalized scores but its runtime does not`);
+}
+/** Expose the configured child identity while preserving the driver methods. */
+function instanceAdapter(adapter, instanceId) {
+	return new Proxy(adapter, { get(target, property) {
+		if (property === "id") return instanceId;
+		const value = Reflect.get(target, property, target);
+		return typeof value === "function" ? value.bind(target) : value;
+	} });
+}
+var MemorySpaceProviderSnapshot = class {
+	digest;
+	entries;
+	constructor(entries) {
+		const sorted = [...entries].sort((left, right) => left.childKey.localeCompare(right.childKey));
+		this.entries = Object.freeze(sorted.map((entry) => Object.freeze({ ...entry })));
+		this.digest = digest(sorted.map((entry) => ({
+			childKey: entry.childKey,
+			instanceId: entry.instanceId,
+			configDigest: entry.configDigest,
+			manifest: semanticManifest(entry.definition.manifest)
+		})), "Memory Space Provider snapshot");
+		Object.freeze(this);
+	}
+	descriptors() {
+		return this.entries.map(({ instanceId, definition }) => ({
+			id: instanceId,
+			...instanceId === definition.manifest.typeId ? {} : { typeId: definition.manifest.typeId },
+			label: definition.manifest.label,
+			...definition.manifest.icon === void 0 ? {} : { icon: structuredClone(definition.manifest.icon) },
+			kind: definition.manifest.locality,
+			workspaceBinding: definition.manifest.workspaceBinding,
+			summary: definition.manifest.summary,
+			...definition.manifest.summaryI18nKey === void 0 ? {} : { summaryI18nKey: definition.manifest.summaryI18nKey },
+			origin: definition.manifest.origin,
+			capabilities: structuredClone(definition.manifest.capabilities),
+			fields: structuredClone(definition.manifest.fields)
+		}));
+	}
+	adapterRegistry() {
+		return new MemoryProviderAdapterRegistry(this.entries.map(({ instanceId, definition }) => ({
+			id: instanceId,
+			create: (context) => {
+				const adapter = definition.create({
+					...context,
+					providerInstanceId: instanceId,
+					manifest: definition.manifest
+				});
+				assertRuntime(definition, adapter);
+				return instanceAdapter(adapter, instanceId);
+			}
+		})));
+	}
+};
+/**
+* Source-private definition host. It is a plain closure-owned object, never a
+* Cordis Context service and never a Mnemon contribution registry.
+*/
+var PrivateMemorySpaceProviderHost = class {
+	sourceInstanceId;
+	registrations = /* @__PURE__ */ new Map();
+	constructor(sourceInstanceId) {
+		this.sourceInstanceId = sourceInstanceId;
+		this.sourceInstanceId = requiredSourceInstanceId(sourceInstanceId);
+	}
+	bind(instanceIdValue, moduleTypeIdValue, config) {
+		const instanceId = requiredId(instanceIdValue, "Memory Space Provider instanceId");
+		const moduleTypeId = requiredId(moduleTypeIdValue, "Memory Space Provider module id");
+		const childKey = `${this.sourceInstanceId}/provider:${instanceId}`;
+		const configDigest = digest(config ?? null, `Memory Space Provider ${instanceId} config`);
+		let installed = false;
+		return Object.freeze({ install: (owner, definitionValue) => {
+			if (installed) throw new Error(`Memory Space Provider child already installed a definition: ${childKey}`);
+			const definition = defineMemorySpaceProviderDefinition(definitionValue);
+			if (definition.manifest.typeId !== moduleTypeId) throw new Error(`Memory Space Provider module ${moduleTypeId} installed definition ${definition.manifest.typeId}`);
+			installed = true;
+			return owner.effect(() => {
+				if (this.registrations.has(childKey)) throw new Error(`Memory Space Provider child is already installed: ${childKey}`);
+				const registration = Object.freeze({
+					childKey,
+					instanceId,
+					configDigest,
+					definition
+				});
+				this.registrations.set(childKey, registration);
+				let active = true;
+				return () => {
+					if (!active) return;
+					active = false;
+					if (this.registrations.get(childKey) === registration) this.registrations.delete(childKey);
+				};
+			}, `dsh-mnemon: install private Provider ${childKey}`);
+		} });
+	}
+	has(instanceId) {
+		return this.registrations.has(`${this.sourceInstanceId}/provider:${instanceId}`);
+	}
+	snapshot() {
+		return new MemorySpaceProviderSnapshot([...this.registrations.values()]);
+	}
+};
+//#endregion
+//#region src/providers/plugin.ts
+/**
+* Build an ordinary child plugin whose only capability is a closure-held
+* registration into its Memory Spaces parent. No ctx.mnemonProvider service
+* exists, and core cannot resolve this host.
+*/
+function createMemorySpaceProviderPlugin(entry, host) {
+	const plugin = {
+		name: `dsh-mnemon-provider-${entry.module.id}`,
+		apply(ctx, config = entry.config) {
+			return entry.module.apply(ctx, host.bind(entry.instanceId, entry.module.id, config), config);
+		}
+	};
+	if (entry.module.Config !== void 0) plugin.Config = entry.module.Config;
+	return plugin;
+}
+//#endregion
+export { MemoryProviderCatalog as a, EMPTY_MEMORY_PROVIDER_CATALOG as i, PrivateMemorySpaceProviderHost as n, MemoryProviderAdapterRegistry as r, createMemorySpaceProviderPlugin as t };

package/lib/process-B-t3UflO.js

@@ -0,0 +1,81 @@
+import { spawn } from "node:child_process";
+//#region src/providers/adapter.ts
+const NORMALIZED_RELEVANCE_SCORE = Object.freeze({ kind: "normalized-relevance" });
+//#endregion
+//#region src/providers/process.ts
+const DEFAULT_MAX_OUTPUT_BYTES = 2097152;
+/** Spawn without a shell, with bounded output and cooperative cancellation. */
+const runProcess = (command, args, options) => new Promise((resolve, reject) => {
+	const label = options.label ?? "mnemon";
+	const child = spawn(command, [...args], {
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		shell: false,
+		windowsHide: true,
+		...options.cwd === void 0 ? {} : { cwd: options.cwd },
+		...options.env === void 0 ? {} : { env: options.env }
+	});
+	const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+	let stdout = "";
+	let stderr = "";
+	let outputBytes = 0;
+	let settled = false;
+	let killTimer;
+	const stop = () => {
+		if (child.exitCode !== null || child.signalCode !== null) return;
+		child.kill("SIGTERM");
+		killTimer = setTimeout(() => {
+			if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+		}, 1500);
+	};
+	const finish = (error, result) => {
+		if (settled) return;
+		settled = true;
+		clearTimeout(timeout);
+		if (killTimer !== void 0) clearTimeout(killTimer);
+		options.signal?.removeEventListener("abort", abort);
+		if (error === null) resolve(result);
+		else reject(error);
+	};
+	const abort = () => {
+		stop();
+		finish(/* @__PURE__ */ new Error(`${label} command aborted: ${String(options.signal?.reason ?? "cancelled")}`));
+	};
+	const append = (target, chunk) => {
+		outputBytes += chunk.byteLength;
+		if (outputBytes > maxOutputBytes) {
+			stop();
+			finish(/* @__PURE__ */ new Error(`${label} output exceeded ${maxOutputBytes} bytes`));
+			return;
+		}
+		if (target === "stdout") stdout += chunk.toString("utf8");
+		else stderr += chunk.toString("utf8");
+	};
+	child.stdout.on("data", (chunk) => {
+		append("stdout", chunk);
+	});
+	child.stderr.on("data", (chunk) => {
+		append("stderr", chunk);
+	});
+	child.on("error", (error) => {
+		finish(/* @__PURE__ */ new Error(`failed to launch ${label} (${JSON.stringify(command)}): ${error.message}`));
+	});
+	child.on("close", (exitCode) => {
+		finish(null, {
+			stdout,
+			stderr,
+			exitCode
+		});
+	});
+	const timeout = setTimeout(() => {
+		stop();
+		finish(/* @__PURE__ */ new Error(`${label} did not respond within ${options.timeoutMs}ms`));
+	}, options.timeoutMs);
+	if (options.signal?.aborted === true) abort();
+	else options.signal?.addEventListener("abort", abort, { once: true });
+});
+//#endregion
+export { NORMALIZED_RELEVANCE_SCORE as n, runProcess as t };

package/lib/provider-sdk.d.ts

@@ -0,0 +1,54 @@
+import { CATEGORIES, Category, EDGE_TYPES, EdgeType, INTENTS, Insight, Intent, JsonValue, MemoryBody, MemoryBodyProvider, MemoryBodyStats, MemoryGraphEdge, MemoryGraphNode, MemoryGraphSnapshot, MemoryListRequest, MemoryProviderCapabilities, MemoryProviderConfigField, MemoryProviderConfigOption, MemoryProviderConnection, MemoryProviderConnectionValue, MemoryProviderDescriptor, MemoryProviderIcon, MemoryProviderId, OpenVikingBodyConnection, RememberRequest, SOURCES, SearchRequest, Source } from "./contracts.js";
+import { _ as NORMALIZED_RELEVANCE_SCORE, a as MemorySpaceProviderHost, b as ProviderScoreSemantics, c as MemorySpaceProviderRuntimeContext, d as defineMemorySpaceProviderDefinition, f as MemoryProviderAdapter, g as MemorySpaceNativeRunner, h as MemorySpaceAuthority, i as MemorySpaceProviderEntry, l as MemorySpaceProviderScoreSemantics, m as MemoryProviderScoreSemantics, n as MemorySpaceProviderDefinition, o as MemorySpaceProviderManifest, p as MemoryProviderAdapterFactoryContext, r as MemorySpaceProviderDisposer, s as MemorySpaceProviderModule, t as MEMORY_SPACE_PROVIDER_API_VERSION, u as defineMemorySpaceProvider, v as ProviderBodyStatus, x as ProviderSearchResult, y as ProviderMemorySpace } from "./definitions-CEpa-tvm.js";
+//#region src/providers/http.d.ts
+interface HttpProviderOptions {
+  label?: string;
+  fetch?: typeof fetch;
+  requestTimeoutMs?: number;
+}
+interface JsonRequestOptions {
+  method?: string;
+  headers?: HeadersInit;
+  json?: JsonValue;
+  signal?: AbortSignal | undefined;
+  timeoutMs?: number;
+}
+declare function jsonObject(value: unknown): Record<string, unknown> | undefined;
+declare function jsonString(value: unknown): string | undefined;
+declare function jsonNumber(value: unknown): number | undefined;
+declare function jsonArray(value: unknown): unknown[];
+declare function firstArray(value: unknown, ...keys: string[]): unknown[];
+/** Shared timeout, cancellation, error, and projection behavior for HTTP providers. */
+declare abstract class HttpMemoryProvider {
+  protected readonly memoryBodies: MemorySpaceAuthority;
+  abstract readonly id: MemoryProviderId;
+  protected readonly label: string | undefined;
+  protected readonly requestFetch: typeof fetch;
+  protected readonly requestTimeoutMs: number;
+  constructor(memoryBodies: MemorySpaceAuthority, options?: HttpProviderOptions);
+  abstract list(body: MemoryBody, request: MemoryListRequest, signal?: AbortSignal): Promise<Insight[]>;
+  graph(body: MemoryBody, signal?: AbortSignal): Promise<MemoryGraphSnapshot>;
+  protected connection(body: MemoryBody): MemoryProviderConnection;
+  protected request(body: MemoryBody, path: string, options?: JsonRequestOptions): Promise<unknown>;
+  protected requestConnection(connection: MemoryProviderConnection, path: string, options?: JsonRequestOptions): Promise<unknown>;
+}
+//#endregion
+//#region src/providers/process.d.ts
+interface ProcessResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+}
+interface ProcessOptions {
+  signal?: AbortSignal | undefined;
+  timeoutMs: number;
+  maxOutputBytes?: number;
+  cwd?: string | undefined;
+  env?: NodeJS.ProcessEnv | undefined;
+  label?: string | undefined;
+}
+type ProcessRunner = (command: string, args: readonly string[], options: ProcessOptions) => Promise<ProcessResult>;
+/** Spawn without a shell, with bounded output and cooperative cancellation. */
+declare const runProcess: ProcessRunner;
+//#endregion
+export { CATEGORIES, type Category, EDGE_TYPES, type EdgeType, HttpMemoryProvider, HttpProviderOptions, INTENTS, type Insight, type Intent, JsonRequestOptions, type JsonValue, MEMORY_SPACE_PROVIDER_API_VERSION, type MemoryBody, type MemoryBodyProvider, type MemoryBodyStats, type MemoryGraphEdge, type MemoryGraphNode, type MemoryGraphSnapshot, type MemoryListRequest, MemoryProviderAdapter, MemoryProviderAdapterFactoryContext, type MemoryProviderCapabilities, type MemoryProviderConfigField, type MemoryProviderConfigOption, type MemoryProviderConnection, type MemoryProviderConnectionValue, type MemoryProviderDescriptor, type MemoryProviderIcon, type MemoryProviderId, MemoryProviderScoreSemantics, MemorySpaceAuthority, MemorySpaceNativeRunner, type MemorySpaceProviderDefinition, type MemorySpaceProviderDisposer, type MemorySpaceProviderEntry, type MemorySpaceProviderHost, type MemorySpaceProviderManifest, type MemorySpaceProviderModule, type MemorySpaceProviderRuntimeContext, type MemorySpaceProviderScoreSemantics, NORMALIZED_RELEVANCE_SCORE, type OpenVikingBodyConnection, ProcessOptions, ProcessResult, ProcessRunner, ProviderBodyStatus, ProviderMemorySpace, ProviderScoreSemantics, ProviderSearchResult, type RememberRequest, SOURCES, type SearchRequest, type Source, defineMemorySpaceProvider, defineMemorySpaceProviderDefinition, firstArray, jsonArray, jsonNumber, jsonObject, jsonString, runProcess };

package/lib/provider-sdk.js

@@ -0,0 +1,105 @@
+import { CATEGORIES, EDGE_TYPES, INTENTS, SOURCES } from "./contracts.js";
+import { n as NORMALIZED_RELEVANCE_SCORE, t as runProcess } from "./process-B-t3UflO.js";
+import { i as defineMemorySpaceProviderDefinition, r as defineMemorySpaceProvider, t as MEMORY_SPACE_PROVIDER_API_VERSION } from "./definitions-DfmOqJjR.js";
+//#region src/providers/http.ts
+function jsonObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+function jsonString(value) {
+	return typeof value === "string" ? value : void 0;
+}
+function jsonNumber(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function jsonArray(value) {
+	return Array.isArray(value) ? value : [];
+}
+function firstArray(value, ...keys) {
+	if (Array.isArray(value)) return value;
+	const root = jsonObject(value);
+	for (const key of keys) if (Array.isArray(root?.[key])) return root[key];
+	const nested = jsonObject(root?.data);
+	for (const key of keys) if (Array.isArray(nested?.[key])) return nested[key];
+	return [];
+}
+function errorDetail(payload) {
+	if (typeof payload === "string") return payload.trim() || void 0;
+	const root = jsonObject(payload);
+	const direct = jsonString(root?.message) ?? jsonString(root?.error) ?? jsonString(root?.detail);
+	if (direct !== void 0) return direct;
+	const error = jsonObject(root?.error);
+	return jsonString(error?.message) ?? jsonString(error?.detail);
+}
+/** Shared timeout, cancellation, error, and projection behavior for HTTP providers. */
+var HttpMemoryProvider = class {
+	memoryBodies;
+	label;
+	requestFetch;
+	requestTimeoutMs;
+	constructor(memoryBodies, options = {}) {
+		this.memoryBodies = memoryBodies;
+		this.label = options.label;
+		this.requestFetch = options.fetch ?? globalThis.fetch;
+		this.requestTimeoutMs = options.requestTimeoutMs ?? 15e3;
+	}
+	async graph(body, signal) {
+		return {
+			nodes: (await this.list(body, { limit: 200 }, signal)).map((item) => ({
+				...item,
+				color: "#6574d9"
+			})),
+			edges: [],
+			generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+	}
+	connection(body) {
+		if ((body.provider.typeId ?? body.provider.id) !== this.id) throw new Error(`${this.id} cannot serve provider ${body.provider.id}`);
+		return this.memoryBodies.providerConnection(body.id, body.provider.id);
+	}
+	async request(body, path, options = {}) {
+		const connection = this.connection(body);
+		return this.requestConnection(connection, path, options);
+	}
+	async requestConnection(connection, path, options = {}) {
+		const endpoint = String(connection.endpoint ?? "").replace(/\/+$/u, "");
+		const label = this.label ?? this.id;
+		if (endpoint === "") throw new Error(`${label} endpoint is not configured`);
+		if (!path.startsWith("/")) throw new Error(`${label} request path must be absolute`);
+		options.signal?.throwIfAborted();
+		const controller = new AbortController();
+		const relay = () => controller.abort(options.signal?.reason);
+		options.signal?.addEventListener("abort", relay, { once: true });
+		const timeoutMs = options.timeoutMs ?? this.requestTimeoutMs;
+		const timer = setTimeout(() => controller.abort(/* @__PURE__ */ new Error(`${label} request timed out`)), timeoutMs);
+		const headers = new Headers(options.headers);
+		if (options.json !== void 0 && !headers.has("Content-Type")) headers.set("Content-Type", "application/json");
+		try {
+			const response = await this.requestFetch(`${endpoint}${path}`, {
+				method: options.method ?? (options.json === void 0 ? "GET" : "POST"),
+				headers,
+				...options.json === void 0 ? {} : { body: JSON.stringify(options.json) },
+				signal: controller.signal
+			});
+			const raw = await response.text();
+			let payload = {};
+			if (raw !== "") try {
+				payload = JSON.parse(raw);
+			} catch {
+				payload = raw;
+			}
+			if (!response.ok) {
+				const detail = errorDetail(payload);
+				throw new Error(`${label} HTTP ${response.status}${detail === void 0 ? "" : `: ${detail}`}`);
+			}
+			return payload;
+		} catch (error) {
+			if (controller.signal.aborted && options.signal?.aborted !== true) throw new Error(`${label} request timed out after ${timeoutMs}ms`);
+			throw error;
+		} finally {
+			clearTimeout(timer);
+			options.signal?.removeEventListener("abort", relay);
+		}
+	}
+};
+//#endregion
+export { CATEGORIES, EDGE_TYPES, HttpMemoryProvider, INTENTS, MEMORY_SPACE_PROVIDER_API_VERSION, NORMALIZED_RELEVANCE_SCORE, SOURCES, defineMemorySpaceProvider, defineMemorySpaceProviderDefinition, firstArray, jsonArray, jsonNumber, jsonObject, jsonString, runProcess };

package/lib/testing.d.ts

@@ -0,0 +1,28 @@
+import { MemoryBody, MemoryProviderConnection, MemoryProviderDescriptor } from "./contracts.js";
+import { f as MemoryProviderAdapter, h as MemorySpaceAuthority, o as MemorySpaceProviderManifest, p as MemoryProviderAdapterFactoryContext, s as MemorySpaceProviderModule } from "./definitions-CEpa-tvm.js";
+//#region src/testing.d.ts
+interface MemorySpaceProviderTest {
+  readonly registered: boolean;
+  readonly descriptor: MemoryProviderDescriptor;
+  readonly manifest: MemorySpaceProviderManifest;
+  createAdapter(context: MemoryProviderAdapterFactoryContext): MemoryProviderAdapter;
+  dispose(): Promise<void>;
+}
+/** Real private-child registration and factory validation, without exposing its Host/Registry. */
+declare function mountMemorySpaceProvider<C>(module: MemorySpaceProviderModule<C>, options: {
+  instanceId?: string;
+  sourceInstanceId?: string;
+  config: C;
+}): Promise<MemorySpaceProviderTest>;
+/** Driver fixture only: real descriptor validation, no Core or service singleton. */
+declare function createMemorySpaceProviderFixture(descriptor: MemoryProviderDescriptor, input: MemoryProviderConnection | undefined, options: {
+  dataDir: string;
+  instanceId?: string;
+  memoryBodyId?: string;
+}): {
+  body: MemoryBody;
+  authority: MemorySpaceAuthority;
+  connection: MemoryProviderConnection;
+};
+//#endregion
+export { MemorySpaceProviderTest, createMemorySpaceProviderFixture, mountMemorySpaceProvider };