dsh-mnemon 0.2.16 → 0.3.1

package/lib/contracts.js

@@ -0,0 +1,36 @@
+//#region packages/contracts/src/index.ts
+const BUILTIN_MEMORY_LAYER_IDS = [
+	"runtime",
+	"documents",
+	"memory-spaces"
+];
+const MEMORY_CAPABILITIES = [
+	"status",
+	"project",
+	"recall",
+	"search",
+	"read",
+	"browse",
+	"write",
+	"archive",
+	"graph",
+	"related",
+	"link",
+	"forget",
+	"maintain",
+	"export",
+	"import"
+];
+const MEMORY_STRATEGY_HOOKS = [
+	"admission",
+	"placement",
+	"retrieval-planning",
+	"quality-fusion",
+	"projection",
+	"promotion-demotion",
+	"retention",
+	"maintenance"
+];
+const MEMORY_SOURCE_MODES = ["eager", "routed"];
+//#endregion
+export { BUILTIN_MEMORY_LAYER_IDS, MEMORY_CAPABILITIES, MEMORY_SOURCE_MODES, MEMORY_STRATEGY_HOOKS };

package/lib/extension-sdk.js

@@ -0,0 +1,238 @@
+//#region packages/extension-sdk/src/index.ts
+const EXTENSION_ID = /^[a-z][a-z0-9-]{0,127}$/u;
+function reverseDispose(disposers) {
+	for (const dispose of disposers.reverse()) dispose();
+}
+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 captureExtension(extension, id) {
+	const layers = extension.layers?.map((registration) => Object.freeze({
+		descriptor: deepFreeze(structuredClone(registration.descriptor)),
+		...registration.execute === void 0 ? {} : { execute: registration.execute }
+	}));
+	const adapters = extension.adapters?.map((registration) => Object.freeze({ descriptor: deepFreeze(structuredClone(registration.descriptor)) }));
+	const strategies = extension.strategies?.map((registration) => Object.freeze({
+		descriptor: deepFreeze(structuredClone(registration.descriptor)),
+		propose: registration.propose
+	}));
+	const sources = extension.sources?.map((source) => Object.freeze({
+		layerId: source.layerId,
+		mode: source.mode,
+		snapshot: source.snapshot
+	}));
+	const guards = extension.guards?.map((guard) => Object.freeze({
+		id: guard.id,
+		decide: guard.decide
+	}));
+	return Object.freeze({
+		descriptor: deepFreeze({
+			...structuredClone(extension.descriptor),
+			id
+		}),
+		...layers === void 0 ? {} : { layers: Object.freeze(layers) },
+		...adapters === void 0 ? {} : { adapters: Object.freeze(adapters) },
+		...strategies === void 0 ? {} : { strategies: Object.freeze(strategies) },
+		...sources === void 0 ? {} : { sources: Object.freeze(sources) },
+		...guards === void 0 ? {} : { guards: Object.freeze(guards) }
+	});
+}
+/**
+* Minimal Boot assembler for one Host. It applies the same captured extension
+* set to every runtime graph while each graph owns its Catalog, Kernel, and
+* TurnView state. Cordis remains responsible for lifecycle and isolation.
+*/
+var MemoryBoot = class {
+	extensions = /* @__PURE__ */ new Map();
+	targets = /* @__PURE__ */ new Set();
+	register(extension) {
+		const id = extension.descriptor.id.trim();
+		if (!EXTENSION_ID.test(id)) throw new Error("memory extension id must match [a-z][a-z0-9-]{0,127}");
+		if (this.extensions.has(id)) throw new Error(`memory extension is already registered: ${id}`);
+		const normalized = captureExtension(extension, id);
+		const applied = [];
+		try {
+			for (const target of this.targets) {
+				target.releases.set(id, this.applyChecked(normalized, target));
+				applied.push(target);
+			}
+		} catch (error) {
+			for (const target of applied.reverse()) {
+				target.releases.get(id)?.();
+				target.releases.delete(id);
+			}
+			throw error;
+		}
+		this.extensions.set(id, normalized);
+		let active = true;
+		return () => {
+			if (!active) return;
+			if (this.extensions.get(id) !== normalized) {
+				active = false;
+				return;
+			}
+			this.unregister(normalized);
+			active = false;
+		};
+	}
+	attach(catalog) {
+		const target = {
+			catalog,
+			releases: /* @__PURE__ */ new Map(),
+			released: false
+		};
+		try {
+			for (const extension of this.extensions.values()) target.releases.set(extension.descriptor.id, this.apply(extension, target));
+		} catch (error) {
+			reverseDispose([...target.releases.values()]);
+			throw error;
+		}
+		this.targets.add(target);
+		return {
+			bindKernel: (kernel) => {
+				if (target.released) throw new Error("memory extension attachment is released");
+				if (target.kernel !== void 0) throw new Error("memory extension attachment already has a kernel");
+				target.kernel = kernel;
+				const guardReleases = /* @__PURE__ */ new Map();
+				try {
+					for (const extension of this.extensions.values()) {
+						const disposers = [];
+						try {
+							for (const guard of extension.guards ?? []) disposers.push(kernel.registerGuard(guard));
+							guardReleases.set(extension.descriptor.id, () => reverseDispose(disposers));
+						} catch (error) {
+							reverseDispose(disposers);
+							throw error;
+						}
+					}
+					for (const [id, releaseGuards] of guardReleases) {
+						const releaseCatalog = target.releases.get(id) ?? (() => {});
+						target.releases.set(id, () => {
+							releaseGuards();
+							releaseCatalog();
+						});
+					}
+				} catch (error) {
+					reverseDispose([...guardReleases.values()]);
+					delete target.kernel;
+					throw error;
+				}
+			},
+			bindTurnViews: (manager) => {
+				if (target.released) throw new Error("memory extension attachment is released");
+				if (target.viewManager !== void 0) throw new Error("memory Boot attachment already has a TurnView manager");
+				target.viewManager = manager;
+				const sourceReleases = /* @__PURE__ */ new Map();
+				try {
+					for (const extension of this.extensions.values()) {
+						const disposers = [];
+						try {
+							for (const source of extension.sources ?? []) {
+								if (target.catalog.layer(source.layerId) === void 0) throw new Error(`MemorySource layer is unavailable: ${source.layerId}`);
+								disposers.push(manager.registerSource(source));
+							}
+							sourceReleases.set(extension.descriptor.id, () => reverseDispose(disposers));
+						} catch (error) {
+							reverseDispose(disposers);
+							throw error;
+						}
+					}
+					manager.assertSourcesReady();
+					for (const [id, releaseSources] of sourceReleases) {
+						const releasePrevious = target.releases.get(id) ?? (() => {});
+						target.releases.set(id, () => {
+							releaseSources();
+							releasePrevious();
+						});
+					}
+				} catch (error) {
+					reverseDispose([...sourceReleases.values()]);
+					delete target.viewManager;
+					throw error;
+				}
+			},
+			dispose: () => {
+				if (target.released) return;
+				target.released = true;
+				this.targets.delete(target);
+				reverseDispose([...target.releases.values()]);
+				target.releases.clear();
+			},
+			release: () => {
+				if (target.released) return;
+				target.released = true;
+				this.targets.delete(target);
+				target.releases.clear();
+			}
+		};
+	}
+	descriptors() {
+		return [...this.extensions.values()].map((extension) => ({ ...extension.descriptor })).sort((left, right) => left.id.localeCompare(right.id));
+	}
+	apply(extension, target) {
+		const disposers = [];
+		try {
+			for (const layer of extension.layers ?? []) disposers.push(target.catalog.registerLayer(layer));
+			for (const adapter of extension.adapters ?? []) disposers.push(target.catalog.registerAdapter(adapter));
+			for (const strategy of extension.strategies ?? []) disposers.push(target.catalog.registerStrategy(strategy));
+			if (target.kernel !== void 0) for (const guard of extension.guards ?? []) disposers.push(target.kernel.registerGuard(guard));
+			if (target.viewManager !== void 0) for (const source of extension.sources ?? []) {
+				if (target.catalog.layer(source.layerId) === void 0) throw new Error(`MemorySource layer is unavailable: ${source.layerId}`);
+				disposers.push(target.viewManager.registerSource(source));
+			}
+			return () => reverseDispose(disposers);
+		} catch (error) {
+			reverseDispose(disposers);
+			throw error;
+		}
+	}
+	applyChecked(extension, target) {
+		const release = this.apply(extension, target);
+		try {
+			target.viewManager?.assertSourcesReady();
+			return release;
+		} catch (error) {
+			release();
+			throw error;
+		}
+	}
+	/** Remove one global extension from every live graph, or restore it everywhere. */
+	unregister(extension) {
+		const id = extension.descriptor.id;
+		const removed = [];
+		try {
+			for (const target of this.targets) {
+				const release = target.releases.get(id);
+				if (release === void 0) continue;
+				release();
+				target.releases.delete(id);
+				removed.push(target);
+				target.viewManager?.assertSourcesReady();
+			}
+		} catch (error) {
+			const rollbackFailures = [];
+			for (const target of removed.reverse()) try {
+				target.releases.set(id, this.applyChecked(extension, target));
+			} catch (rollbackError) {
+				rollbackFailures.push(rollbackError);
+			}
+			if (rollbackFailures.length > 0) throw new AggregateError([error, ...rollbackFailures], `memory extension ${id} unload failed and could not be fully rolled back`);
+			throw error;
+		}
+		this.extensions.delete(id);
+	}
+};
+function defineMemoryExtension(extension) {
+	return extension;
+}
+/** Process-global Boot, allowing extensions to contribute before the DSH Host mounts. */
+const memoryBoot = new MemoryBoot();
+/** Compatibility name for the v0.3 pre-release API. */
+const memoryExtensions = memoryBoot;
+function registerMemoryExtension(extension) {
+	return memoryBoot.register(extension);
+}
+//#endregion
+export { MemoryBoot, MemoryBoot as MemoryExtensionHost, defineMemoryExtension, memoryBoot, memoryExtensions, registerMemoryExtension };