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

package/lib/definitions-DfmOqJjR.js

@@ -0,0 +1,214 @@
+import { createHash } from "node:crypto";
+//#region src/providers/definitions.ts
+const MEMORY_SPACE_PROVIDER_API_VERSION = "dsh-mnemon.memory-space-provider/v1";
+const STABLE_ID = /^[a-z][a-z0-9-]{0,127}$/u;
+const FIELD_KEY = /^[a-z][a-zA-Z0-9_-]{0,127}$/u;
+function requiredId(value, label) {
+	const normalized = value.trim();
+	if (!STABLE_ID.test(normalized)) throw new Error(`${label} must match [a-z][a-z0-9-]{0,127}`);
+	return normalized;
+}
+function requiredText(value, label, max = 500) {
+	const normalized = value.trim();
+	if (normalized === "") throw new Error(`${label} is required`);
+	if (normalized.length > max) throw new Error(`${label} is too long (max ${max} characters)`);
+	return normalized;
+}
+function requiredFieldKey(value, label) {
+	const normalized = value.trim();
+	if (!FIELD_KEY.test(normalized)) throw new Error(`${label} must start with a letter and contain only letters, digits, _ or -`);
+	return normalized;
+}
+function captureIcon(value) {
+	if (value === void 0) return void 0;
+	const icon = structuredClone(value);
+	if (icon.kind === "brand") icon.value = requiredId(icon.value, "Memory Space Provider icon brand");
+	else if (icon.kind === "glyph") icon.value = requiredText(icon.value, "Memory Space Provider icon glyph", 16);
+	else if (icon.kind === "data-url") {
+		icon.value = requiredText(icon.value, "Memory Space Provider icon data URL", 2e5);
+		if (!/^data:image\/(?:png|jpeg|webp|svg\+xml);base64,[a-zA-Z0-9+/=]+$/u.test(icon.value)) throw new Error("Memory Space Provider icon must be a base64 image data URL");
+	} else throw new Error(`unsupported Memory Space Provider icon kind: ${String(icon.kind)}`);
+	return icon;
+}
+function captureCapabilities(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("Memory Space Provider capabilities must be an object");
+	const capabilities = structuredClone(value);
+	for (const key of [
+		"search",
+		"browse",
+		"graph",
+		"entities",
+		"related",
+		"remember",
+		"link",
+		"forget"
+	]) if (typeof capabilities[key] !== "boolean") throw new Error(`Memory Space Provider capability ${key} must be boolean`);
+	if (capabilities.writeMode !== "exact" && capabilities.writeMode !== "async-extracting") throw new Error("unsupported Memory Space Provider write mode");
+	if (![
+		"soft",
+		"hard",
+		"unsupported"
+	].includes(capabilities.deletionMode)) throw new Error("unsupported Memory Space Provider deletion mode");
+	return capabilities;
+}
+function captureFields(value) {
+	if (!Array.isArray(value)) throw new Error("Memory Space Provider fields must be an array");
+	const fields = structuredClone(value);
+	const fieldKeys = /* @__PURE__ */ new Set();
+	for (const field of fields) {
+		const key = requiredFieldKey(field.key, "Memory Space Provider field key");
+		if (fieldKeys.has(key)) throw new Error(`duplicate Memory Space Provider field: ${key}`);
+		fieldKeys.add(key);
+		field.key = key;
+		field.label = requiredText(field.label, `Memory Space Provider field ${key} label`, 100);
+		if (field.i18nKey !== void 0) field.i18nKey = requiredText(field.i18nKey, `Memory Space Provider field ${key} i18nKey`, 200);
+		if (field.scope !== "service" && field.scope !== "memory") throw new Error(`unsupported Memory Space Provider field scope: ${String(field.scope)}`);
+		if (![
+			"text",
+			"url",
+			"secret",
+			"number",
+			"boolean",
+			"select",
+			"path"
+		].includes(field.input)) throw new Error(`unsupported Memory Space Provider field input: ${String(field.input)}`);
+		if (typeof field.required !== "boolean") throw new Error(`Memory Space Provider field ${key} required must be boolean`);
+		if (field.role !== void 0 && field.role !== "global-location") throw new Error(`unsupported Memory Space Provider field role: ${String(field.role)}`);
+		if (field.role === "global-location" && (field.scope !== "service" || field.input !== "path")) throw new Error(`Memory Space Provider field ${key} global-location must be a service path`);
+		if (field.placeholder !== void 0) field.placeholder = requiredText(field.placeholder, `Memory Space Provider field ${key} placeholder`, 2e3);
+		if (field.help !== void 0) field.help = requiredText(field.help, `Memory Space Provider field ${key} help`, 2e3);
+		if (field.min !== void 0 && (!Number.isFinite(field.min) || field.input !== "number")) throw new Error(`Memory Space Provider field ${key} min requires a finite number field`);
+		if (field.max !== void 0 && (!Number.isFinite(field.max) || field.input !== "number")) throw new Error(`Memory Space Provider field ${key} max requires a finite number field`);
+		if (field.min !== void 0 && field.max !== void 0 && field.min > field.max) throw new Error(`Memory Space Provider field ${key} min exceeds max`);
+		if (field.maxLength !== void 0 && (![
+			"text",
+			"url",
+			"secret",
+			"select",
+			"path"
+		].includes(field.input) || !Number.isInteger(field.maxLength) || field.maxLength < 1 || field.maxLength > 8e3)) throw new Error(`Memory Space Provider field ${key} maxLength is invalid`);
+		if (field.pattern !== void 0) {
+			if (![
+				"text",
+				"url",
+				"secret",
+				"path"
+			].includes(field.input)) throw new Error(`Memory Space Provider field ${key} pattern requires a textual field`);
+			field.pattern = requiredText(field.pattern, `Memory Space Provider field ${key} pattern`, 1e3);
+			try {
+				new RegExp(field.pattern, "u");
+			} catch {
+				throw new Error(`Memory Space Provider field ${key} pattern is invalid`);
+			}
+		}
+		if (field.validationMessage !== void 0) {
+			if (field.pattern === void 0) throw new Error(`Memory Space Provider field ${key} validationMessage requires a pattern`);
+			field.validationMessage = requiredText(field.validationMessage, `Memory Space Provider field ${key} validationMessage`, 500);
+		}
+		if (field.normalize !== void 0 && (field.normalize !== "trim-trailing-slash" || ![
+			"text",
+			"url",
+			"path"
+		].includes(field.input))) throw new Error(`unsupported Memory Space Provider field normalization: ${String(field.normalize)}`);
+		if (field.options !== void 0) {
+			if (field.input !== "select" || field.options.length === 0) throw new Error(`Memory Space Provider field ${key} options require a non-empty select field`);
+			const optionValues = /* @__PURE__ */ new Set();
+			for (const option of field.options) {
+				option.value = requiredText(option.value, `Memory Space Provider field ${key} option value`, 200);
+				option.label = requiredText(option.label, `Memory Space Provider field ${key} option label`, 200);
+				if (option.i18nKey !== void 0) option.i18nKey = requiredText(option.i18nKey, `Memory Space Provider field ${key} option i18nKey`, 200);
+				if (optionValues.has(option.value)) throw new Error(`duplicate Memory Space Provider field ${key} option: ${option.value}`);
+				optionValues.add(option.value);
+			}
+		} else if (field.input === "select") throw new Error(`Memory Space Provider select field ${key} requires options`);
+		if (field.defaultValue !== void 0) {
+			if (!(field.input === "boolean" ? typeof field.defaultValue === "boolean" : field.input === "number" ? typeof field.defaultValue === "number" && Number.isFinite(field.defaultValue) : typeof field.defaultValue === "string") || field.input === "select" && !field.options?.some((option) => option.value === field.defaultValue)) throw new Error(`Memory Space Provider field ${key} default is invalid`);
+		}
+	}
+	for (const field of fields) {
+		if (field.discoveryDefaultFrom === void 0) continue;
+		field.discoveryDefaultFrom = requiredFieldKey(field.discoveryDefaultFrom, `Memory Space Provider field ${field.key} discoveryDefaultFrom`);
+		const source = fields.find((candidate) => candidate.key === field.discoveryDefaultFrom);
+		if (field.scope !== "service" || source?.scope !== "memory" || source.input === "secret") throw new Error(`Memory Space Provider field ${field.key} discovery default must reference a memory field`);
+	}
+	return fields;
+}
+function canonical(value, label, ancestors = /* @__PURE__ */ new Set(), depth = 0) {
+	if (depth > 64) throw new Error(`${label} exceeds the maximum nesting depth`);
+	if (value === null || typeof value === "boolean" || typeof value === "string") return JSON.stringify(value);
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new Error(`${label} contains a non-finite number`);
+		return JSON.stringify(value);
+	}
+	if (typeof value !== "object") throw new Error(`${label} must be JSON-safe`);
+	if (ancestors.has(value)) throw new Error(`${label} contains a cycle`);
+	ancestors.add(value);
+	try {
+		if (Array.isArray(value)) return `[${value.map((item) => canonical(item, label, ancestors, depth + 1)).join(",")}]`;
+		if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) throw new Error(`${label} contains a non-plain object`);
+		return `{${Object.entries(value).filter(([, item]) => item !== void 0).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${canonical(item, label, ancestors, depth + 1)}`).join(",")}}`;
+	} finally {
+		ancestors.delete(value);
+	}
+}
+function digest(value, label) {
+	return createHash("sha256").update(canonical(value, label)).digest("hex");
+}
+function deepFreeze(value) {
+	if (typeof value !== "object" || value === null || Object.isFrozen(value)) return value;
+	for (const child of Object.values(value)) deepFreeze(child);
+	return Object.freeze(value);
+}
+function captureManifest(value) {
+	canonical(value, "Memory Space Provider manifest");
+	const manifest = structuredClone(value);
+	if (manifest.apiVersion !== "dsh-mnemon.memory-space-provider/v1") throw new Error(`unsupported Memory Space Provider API: ${String(manifest.apiVersion)}`);
+	if (manifest.kind !== "provider") throw new Error("Memory Space Provider manifest kind must be provider");
+	manifest.typeId = requiredId(manifest.typeId, "Memory Space Provider typeId");
+	manifest.packageName = requiredText(manifest.packageName, "Memory Space Provider packageName");
+	manifest.version = requiredText(manifest.version, "Memory Space Provider version", 100);
+	manifest.label = requiredText(manifest.label, "Memory Space Provider label", 100);
+	manifest.icon = captureIcon(manifest.icon);
+	manifest.summary = requiredText(manifest.summary, "Memory Space Provider summary", 1e3);
+	if (manifest.summaryI18nKey !== void 0) manifest.summaryI18nKey = requiredText(manifest.summaryI18nKey, "Memory Space Provider summaryI18nKey", 200);
+	if (manifest.locality !== "local" && manifest.locality !== "remote") throw new Error("Memory Space Provider locality must be local or remote");
+	if (manifest.origin !== "native" && manifest.origin !== "third-party") throw new Error("Memory Space Provider origin must be native or third-party");
+	if (![
+		"automatic",
+		"optional-override",
+		"provider-global"
+	].includes(manifest.workspaceBinding)) throw new Error(`unsupported Memory Space Provider workspace binding: ${String(manifest.workspaceBinding)}`);
+	if (![
+		"normalized-relevance",
+		"provider-native",
+		"none"
+	].includes(manifest.scoreSemantics)) throw new Error(`unsupported Memory Space Provider score semantics: ${String(manifest.scoreSemantics)}`);
+	manifest.capabilities = captureCapabilities(manifest.capabilities);
+	manifest.fields = captureFields(manifest.fields);
+	if (!Array.isArray(manifest.secrets)) throw new Error("Memory Space Provider secrets must be an array");
+	const secretFields = manifest.fields.filter((field) => field.input === "secret").map((field) => field.key).sort();
+	const secrets = [...new Set(manifest.secrets.map((secret) => requiredFieldKey(secret, "Memory Space Provider secret")))].sort();
+	if (canonical(secretFields, "Memory Space Provider secret fields") !== canonical(secrets, "Memory Space Provider secrets")) throw new Error("Memory Space Provider secrets must exactly match secret config fields");
+	manifest.secrets = secrets;
+	return deepFreeze(manifest);
+}
+function captureDefinition(value) {
+	if (typeof value?.create !== "function") throw new Error("Memory Space Provider definition requires a create factory");
+	return Object.freeze({
+		manifest: captureManifest(value.manifest),
+		create: value.create
+	});
+}
+function defineMemorySpaceProvider(module) {
+	const id = requiredId(module.id, "Memory Space Provider module id");
+	if (typeof module.apply !== "function") throw new Error(`Memory Space Provider module ${id} requires apply()`);
+	return Object.freeze({
+		...module,
+		id
+	});
+}
+function defineMemorySpaceProviderDefinition(definition) {
+	return captureDefinition(definition);
+}
+//#endregion
+export { digest as a, defineMemorySpaceProviderDefinition as i, deepFreeze as n, requiredId as o, defineMemorySpaceProvider as r, MEMORY_SPACE_PROVIDER_API_VERSION as t };

package/lib/index.d.ts

@@ -0,0 +1,47 @@
+import { AutomaticMemoryPlacementRequest, CATEGORIES, Category, CreateMemoryBodyRequest, DEFAULT_EMBEDDING_ENDPOINT, DEFAULT_EMBEDDING_MODEL, DEFAULT_EMBEDDING_PROTOCOL, EDGE_TYPES, EMBEDDING_PROTOCOL_AUTO, EMBEDDING_PROTOCOL_OLLAMA, EMBEDDING_PROTOCOL_OPENAI, EdgeType, EntityView, INTENTS, Insight, Intent, JsonValue, LlmMemoryPlacementSelection, MNEMON_EMBEDDING_PROTOCOLS, MemoryBody, MemoryBodyCatalog, MemoryBodyMetadataMaintenanceResult, MemoryBodyMetadataSample, MemoryBodyMetadataUpdate, MemoryBodyProvider, MemoryBodyStats, MemoryBodyView, MemoryGraphEdge, MemoryGraphNode, MemoryGraphSnapshot, MemoryListRequest, MemoryListView, MemoryPersistenceStrategy, MemoryPlacementCandidate, MemoryPlacementCapability, MemoryPlacementDecision, MemoryPlacementPreference, MemoryPlacementRules, MemoryProviderCapabilities, MemoryProviderConfigField, MemoryProviderConfigOption, MemoryProviderConnection, MemoryProviderConnectionValue, MemoryProviderDescriptor, MemoryProviderIcon, MemoryProviderId, MemoryProviderRuntimeStatus, MemoryProviderServiceCatalog, MemoryProviderServiceView, MemoryReadMode, MemoryReadSource, MemoryReadStatus, MemorySpacesStatus, MnemonEmbeddingConfig, MnemonEmbeddingProtocol, MnemonEmbeddingStatus, OpenVikingBodyConnection, PreparedMemoryPlacement, RecallQualityConfig, RecallQualityStats, RecallRelevanceTier, RememberRequest, ResolvedMemoryPersistenceStrategy, ResolvedMnemonEmbeddingConfig, ResolvedRecallQualityConfig, SOURCES, SearchRequest, Source, UpdateMemoryBodyRequest, UpdateMemoryProviderServiceRequest } from "./contracts.js";
+import { i as MemorySpaceProviderEntry } from "./definitions-CEpa-tvm.js";
+import z from "schemastery";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/config.d.ts
+interface MemorySpacesConfig {
+  dataDir?: string;
+  cliPath?: string;
+  store?: string;
+  timeoutMs?: number;
+  defaultRecallLimit?: number;
+  writeEnabled?: boolean;
+  embedding?: MnemonEmbeddingConfig;
+  recallQuality?: RecallQualityConfig;
+  persistenceStrategy?: MemoryPersistenceStrategy;
+}
+declare const MemorySpacesConfig: z<MemorySpacesConfig>;
+//#endregion
+//#region src/index.d.ts
+declare const name = "dsh-mnemon-source-memory-spaces";
+declare const inject: string[];
+declare const memoryPlugin: import("dsh-mnemon/extension-sdk").MemoryPluginDescriptor;
+interface Config extends MemorySpacesConfig {
+  /** Explicit Source-private children; resolved by DSH's module Loader. */
+  providers: Array<string | MemorySpaceProviderDeclaration>;
+}
+declare const MemorySpaceProviderDeclarationSchema: z<MemorySpaceProviderDeclaration>;
+declare const Config: z<Config>;
+interface InstallMemorySpacesOptions {
+  config?: MemorySpacesConfig;
+  instanceId?: string;
+}
+interface MemorySpaceProviderDeclaration {
+  /** Installed package specifier; no built-in implementation registry. */
+  use: string;
+  /** Stable child identity; defaults to the module type id when omitted. */
+  instanceId?: string;
+  /** Validated by the child module's Cordis Config schema, when supplied. */
+  config?: unknown;
+}
+/** Resolve only the explicitly listed children; no dependency scanning occurs. */
+declare function resolveMemorySpaceProviderEntries(ctx: Context, declarations: readonly (string | MemorySpaceProviderDeclaration)[]): Promise<MemorySpaceProviderEntry[]>;
+/** Compose an explicit Provider child list into one effective Source. */
+declare function installMemorySpaces(ctx: Context, entries: readonly MemorySpaceProviderEntry[], options?: InstallMemorySpacesOptions): Promise<void>;
+declare function apply(ctx: Context, config?: Config): Promise<void>;
+//#endregion
+export { type AutomaticMemoryPlacementRequest, type CATEGORIES, type Category, Config, type CreateMemoryBodyRequest, type DEFAULT_EMBEDDING_ENDPOINT, type DEFAULT_EMBEDDING_MODEL, type DEFAULT_EMBEDDING_PROTOCOL, type EDGE_TYPES, type EMBEDDING_PROTOCOL_AUTO, type EMBEDDING_PROTOCOL_OLLAMA, type EMBEDDING_PROTOCOL_OPENAI, type EdgeType, type EntityView, type INTENTS, type Insight, InstallMemorySpacesOptions, type Intent, type JsonValue, type LlmMemoryPlacementSelection, type MNEMON_EMBEDDING_PROTOCOLS, type MemoryBody, type MemoryBodyCatalog, type MemoryBodyMetadataMaintenanceResult, type MemoryBodyMetadataSample, type MemoryBodyMetadataUpdate, type MemoryBodyProvider, type MemoryBodyStats, type MemoryBodyView, type MemoryGraphEdge, type MemoryGraphNode, type MemoryGraphSnapshot, type MemoryListRequest, type MemoryListView, type MemoryPersistenceStrategy, type MemoryPlacementCandidate, type MemoryPlacementCapability, type MemoryPlacementDecision, type MemoryPlacementPreference, type MemoryPlacementRules, type MemoryProviderCapabilities, type MemoryProviderConfigField, type MemoryProviderConfigOption, type MemoryProviderConnection, type MemoryProviderConnectionValue, type MemoryProviderDescriptor, type MemoryProviderIcon, type MemoryProviderId, type MemoryProviderRuntimeStatus, type MemoryProviderServiceCatalog, type MemoryProviderServiceView, type MemoryReadMode, type MemoryReadSource, type MemoryReadStatus, MemorySpaceProviderDeclaration, MemorySpaceProviderDeclarationSchema, type MemorySpacesStatus, type MnemonEmbeddingConfig, type MnemonEmbeddingProtocol, type MnemonEmbeddingStatus, type OpenVikingBodyConnection, type PreparedMemoryPlacement, type RecallQualityConfig, type RecallQualityStats, type RecallRelevanceTier, type RememberRequest, type ResolvedMemoryPersistenceStrategy, type ResolvedMnemonEmbeddingConfig, type ResolvedRecallQualityConfig, type SOURCES, type SearchRequest, type Source, type UpdateMemoryBodyRequest, type UpdateMemoryProviderServiceRequest, apply, inject, installMemorySpaces, memoryPlugin, name, resolveMemorySpaceProviderEntries };