dsh-mnemon 0.4.7 → 0.5.0

package/lib/storage-lock-Bqrhkyag.js

@@ -0,0 +1,20 @@
+import { resolve } from "node:path";
+//#region src/sdk/storage-lock.ts
+const queues = /* @__PURE__ */ new Map();
+/**
+* Serialize in-process work on one local storage root, including work from
+* independently loaded plugins. File locks still own cross-process safety.
+* Callers must not acquire the same root recursively.
+*/
+function withMemoryStorageLock(directory, operation) {
+	const key = resolve(directory);
+	const result = (queues.get(key) ?? Promise.resolve()).then(operation);
+	const settled = result.then(() => {}, () => {});
+	queues.set(key, settled);
+	settled.then(() => {
+		if (queues.get(key) === settled) queues.delete(key);
+	});
+	return result;
+}
+//#endregion
+export { withMemoryStorageLock as t };

package/lib/testing.js

@@ -0,0 +1,231 @@
+import { t as provideMemoryRuntime } from "./runtime-AtIOTeP1.js";
+import { DEFAULT_MEMORY_VIEW_BUDGET } from "./contracts.js";
+import { c as jsonClone } from "./definitions-j0FLgE0-.js";
+import { readFileSync } from "node:fs";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/sdk/testing.ts
+/**
+* A test fixture, not a production service or a second Loader. It mounts real
+* Cordis Fibers against the same Runtime/compiler used by the Host. The small
+* Loader identity adapter supplies only stable Entry ids for installMemory.
+* No built-in Source, Provider, database, browser, or private binding is needed.
+*/
+var MemoryCompositionRunner = class {
+	context = new Context();
+	#runtime = provideMemoryRuntime(this.context);
+	#generations;
+	#entryIds = /* @__PURE__ */ new WeakMap();
+	#entries = /* @__PURE__ */ new Map();
+	#turns = /* @__PURE__ */ new Set();
+	#beginnings = /* @__PURE__ */ new Set();
+	#closed = false;
+	#closing;
+	constructor(options = {}) {
+		this.context.provide("loader", {
+			locate: (fiber) => this.#entryIds.get(fiber),
+			import: (specifier) => import(specifier),
+			unwrapExports: (module) => module.default ?? module
+		});
+		const { sourceConfiguration, sourceCapabilities, ...selection } = options;
+		this.#generations = this.#runtime.attachGeneration({
+			...selection,
+			...sourceConfiguration === void 0 ? {} : { sourceConfiguration: (source) => sourceConfiguration(Object.freeze({
+				sourceInstanceKey: source.instanceKey,
+				manifest: source.definition.manifest,
+				provenance: source.provenance
+			})) },
+			...sourceCapabilities === void 0 ? {} : { sourceCapabilities: (source) => sourceCapabilities(Object.freeze({
+				sourceInstanceKey: source.instanceKey,
+				manifest: source.definition.manifest,
+				provenance: source.provenance
+			})) }
+		}).host;
+	}
+	async mount(plugin, entry) {
+		this.#assertOpen();
+		const id = entry.instanceId.trim();
+		if (id === "" || this.#entries.has(id)) throw new Error(`duplicate or empty test Entry id: ${id}`);
+		const boundPlugin = {
+			...plugin,
+			apply: (ctx, config) => {
+				this.#entryIds.set(ctx.fiber, id);
+				return plugin.apply(ctx, config);
+			}
+		};
+		const fiber = this.context.plugin(boundPlugin, entry.config);
+		this.#entries.set(id, fiber);
+		try {
+			await fiber.await();
+			this.#assertOpen();
+		} catch (error) {
+			if (this.#entries.get(id) === fiber) this.#entries.delete(id);
+			await fiber.dispose();
+			throw error;
+		}
+		return async () => {
+			if (this.#entries.get(id) !== fiber) return;
+			this.#entries.delete(id);
+			await fiber.dispose();
+		};
+	}
+	async beginTurn(request = {}, signal) {
+		this.#assertOpen();
+		signal?.throwIfAborted();
+		const budget = { ...request.budget ?? DEFAULT_MEMORY_VIEW_BUDGET };
+		const lease = this.#generations.acquire();
+		const controller = new AbortController();
+		const abort = () => controller.abort(signal.reason);
+		signal?.addEventListener("abort", abort, { once: true });
+		this.#beginnings.add(controller);
+		try {
+			const view = await lease.generation.compose({
+				scope: request.scope ?? { storage: "custom" },
+				scenario: request.scenario ?? "plugin-test",
+				budget
+			}, controller.signal);
+			this.#assertOpen();
+			let active = true;
+			const assertActive = () => {
+				this.#assertOpen();
+				if (!active) throw new Error("Memory test turn is released");
+			};
+			const release = () => {
+				if (!active) return;
+				active = false;
+				this.#turns.delete(release);
+				lease.release();
+			};
+			this.#turns.add(release);
+			return Object.freeze({
+				view,
+				executeRoute: async (routeId, input, signal) => {
+					assertActive();
+					const operation = this.#generations.acquire(lease.id);
+					try {
+						return await operation.generation.executeRoute(view, routeId, input, signal, budget);
+					} finally {
+						operation.release();
+					}
+				},
+				executeAction: async (offerId, input, authorize, signal) => {
+					assertActive();
+					const operation = this.#generations.acquire(lease.id);
+					try {
+						return await operation.generation.executeAction(view, offerId, input, authorize, signal);
+					} finally {
+						operation.release();
+					}
+				},
+				release
+			});
+		} catch (error) {
+			lease.release();
+			throw error;
+		} finally {
+			signal?.removeEventListener("abort", abort);
+			this.#beginnings.delete(controller);
+		}
+	}
+	inspect() {
+		return jsonClone(this.#generations.inspect(), "memory test diagnostics");
+	}
+	async managementCatalog(scope = { storage: "custom" }) {
+		this.#assertOpen();
+		const lease = this.#generations.acquire();
+		try {
+			return await lease.generation.managementCatalog(scope);
+		} finally {
+			lease.release();
+		}
+	}
+	/** Exercise the public protocol, including rejected confirmation/revision cases. */
+	async executeManagement(request) {
+		this.#assertOpen();
+		const lease = this.#generations.acquire();
+		try {
+			return await lease.generation.executeManagement(request);
+		} finally {
+			lease.release();
+		}
+	}
+	/** Same scoped management contract a Source page receives, backed by real generations. */
+	async managementClient(sourceInstanceKey, scopeValue = { storage: "custom" }) {
+		const scope = structuredClone(scopeValue);
+		const instance = (await this.managementCatalog(scope)).sources.find((source) => source.sourceInstanceKey === sourceInstanceKey);
+		if (instance === void 0) throw new Error(`No managed test Source: ${sourceInstanceKey}`);
+		let revision = instance.revision;
+		const execute = async (mode, operation, input, options) => {
+			const result = await this.executeManagement({
+				sourceInstanceKey,
+				scope,
+				mode,
+				operation,
+				input,
+				confirmed: options?.confirmed === true,
+				...mode === "read" ? {} : { expectedRevision: options?.expectedRevision ?? revision }
+			});
+			revision = result.revision;
+			return result;
+		};
+		return {
+			sourceInstanceKey,
+			get revision() {
+				return revision;
+			},
+			read: (operation, input = null) => execute("read", operation, input),
+			mutate: (operation, input, options) => execute("mutate", operation, input, options)
+		};
+	}
+	dispose() {
+		if (this.#closing !== void 0) return this.#closing;
+		this.#closed = true;
+		for (const controller of this.#beginnings) controller.abort(/* @__PURE__ */ new Error("MemoryCompositionRunner is disposed"));
+		for (const release of this.#turns) release();
+		this.#closing = (async () => {
+			const failures = [];
+			for (const fiber of [...this.#entries.values()].reverse()) try {
+				await fiber.dispose();
+			} catch (error) {
+				failures.push(error);
+			}
+			this.#entries.clear();
+			try {
+				await this.context.fiber.dispose();
+			} catch (error) {
+				failures.push(error);
+			}
+			if (failures.length > 0) throw new AggregateError(failures, "MemoryCompositionRunner cleanup failed");
+		})();
+		return this.#closing;
+	}
+	#assertOpen() {
+		if (this.#closed) throw new Error("MemoryCompositionRunner is disposed");
+	}
+};
+/**
+* Evaluate a trusted, already-built DSH Client artifact in a test. Dependencies
+* are explicit (normally the test's React and UI primitives), so no production
+* Loader, global registry, source alias, or second copy of React is required.
+* This is a test fixture, not another Client Loader implementation.
+*/
+function loadMemoryClientArtifact(path, dependencies) {
+	let declaration;
+	const loader = { load(value) {
+		if (declaration !== void 0 || value === void 0 || typeof value.id !== "string" || typeof value.factory !== "function") throw new Error("Expected exactly one DSH Client artifact declaration");
+		declaration = value;
+	} };
+	const actualWindow = globalThis.window ?? {};
+	const window = new Proxy(actualWindow, { get(target, key) {
+		if (key === "__ModuleLoader__") return loader;
+		const value = Reflect.get(target, key, target);
+		return typeof value === "function" ? value.bind(target) : value;
+	} });
+	new Function("window", readFileSync(path, "utf8"))(window);
+	if (declaration === void 0) throw new Error("No DSH Client declaration in artifact");
+	return declaration.factory((id) => {
+		if (!Object.hasOwn(dependencies, id)) throw new Error(`Missing Client test dependency: ${id}`);
+		return dependencies[id];
+	});
+}
+//#endregion
+export { DEFAULT_MEMORY_VIEW_BUDGET, MemoryCompositionRunner, loadMemoryClientArtifact };

package/lib/types/src/client/extension-sdk.d.ts

@@ -0,0 +1,10 @@
+export { installMemorySourceUI, memorySourcePageEntryId, MNEMON_SOURCE_PAGE_SLOT, MNEMON_SOURCE_CONFIGURATION_MUTATE, MNEMON_SOURCE_CONFIGURATION_READ, type MemorySourcePageComponent, type MemorySourcePageDefinition, type MemorySourcePageProps, type MemorySourceUIContribution, type MemorySourceUIContext, type MemorySourcePageNavigation, } from './source-pages.tsx';
+export type { MnemonSourceManagementClient, MemorySourcePageInstance } from './source-contracts.ts';
+export * from './page-kit.tsx';
+export * from './page-client.tsx';
+export { MnemonDialog, type MnemonDialogProps } from './MnemonDialog.tsx';
+export { MnemonLogo } from './MnemonLogo.tsx';
+export { useRequestVersion } from './use-request-version.ts';
+export { appearanceClass } from './view-styles.ts';
+export { translateEn, translateZh, type MnemonKey, type MnemonTranslate } from './locales.ts';
+export { IconChevronLeftOutline14 } from '@deepseek-ai/dsh-client-ui-primitives';

package/lib/types/src/client/index.d.ts

@@ -1,3 +1,4 @@
+export * from './extension-sdk.ts';
 export declare const inject: string[];
 /** Mount the memory workspace plus the optional in-conversation interaction surfaces. */
 export declare function apply(rawContext: unknown): void;

package/lib/types/src/client/locales.d.ts

@@ -10,6 +10,10 @@ export declare const zh: {
     'category.context': string;
     'category.general': string;
     'nav.aria': string;
+    'nav.group.system': string;
+    'nav.group.storage': string;
+    'nav.group.tools': string;
+    'nav.group.sources': string;
     'nav.memory.aria': string;
     'nav.overview': string;
     'nav.bodies': string;
@@ -53,6 +57,34 @@ export declare const zh: {
     'workspace.selectedRoot': string;
     'workspace.effectiveRoot': string;
     'workspace.align': string;
+    'sourcePage.instance': string;
+    'sourcePage.instanceAria': string;
+    'sourcePage.summaryAria': string;
+    'sourcePage.package': string;
+    'sourcePage.availability': string;
+    'sourcePage.availability.ready': string;
+    'sourcePage.availability.degraded': string;
+    'sourcePage.availability.unavailable': string;
+    'sourcePage.role': string;
+    'sourcePage.revision': string;
+    'sourcePage.permissions': string;
+    'sourcePage.diagnostics': string;
+    'sourcePage.configuration': string;
+    'sourcePage.configurationDescription': string;
+    'sourcePage.configLoading': string;
+    'sourcePage.configSave': string;
+    'sourcePage.configSaving': string;
+    'sourcePage.configSaved': string;
+    'sourcePage.secretPlaceholder': string;
+    'sourcePage.unavailable': string;
+    'sourcePage.unavailableDescription': string;
+    'telemetry.aria': string;
+    'telemetry.title': string;
+    'telemetry.memories': string;
+    'telemetry.graph': string;
+    'telemetry.entities': string;
+    'telemetry.spaces': string;
+    'sidebar.activeSpaces': string;
     'overview.title': string;
     'overview.description': string;
     'overview.pageDescription': string;
@@ -689,6 +721,16 @@ export declare const zh: {
     'config.topologyEnabled': string;
     'config.topologyDisabled': string;
     'config.topologyLayerToggle': string;
+    'config.enhancementsTitle': string;
+    'config.enhancementsDescription': string;
+    'config.enhancementCapture': string;
+    'config.enhancementCaptureHint': string;
+    'config.enhancementLightContext': string;
+    'config.enhancementLightContextHint': string;
+    'config.enhancementScoped': string;
+    'config.enhancementScopedHint': string;
+    'config.enhancementsFailed': string;
+    'config.enhancementsRefreshFailed': string;
     'layers.runtimeLabel': string;
     'layers.runtimeDescription': string;
     'layers.documentsLabel': string;
@@ -891,6 +933,10 @@ export declare const en: {
     'category.context': string;
     'category.general': string;
     'nav.aria': string;
+    'nav.group.system': string;
+    'nav.group.storage': string;
+    'nav.group.tools': string;
+    'nav.group.sources': string;
     'nav.memory.aria': string;
     'nav.overview': string;
     'nav.bodies': string;
@@ -934,6 +980,34 @@ export declare const en: {
     'workspace.selectedRoot': string;
     'workspace.effectiveRoot': string;
     'workspace.align': string;
+    'sourcePage.instance': string;
+    'sourcePage.instanceAria': string;
+    'sourcePage.summaryAria': string;
+    'sourcePage.package': string;
+    'sourcePage.availability': string;
+    'sourcePage.availability.ready': string;
+    'sourcePage.availability.degraded': string;
+    'sourcePage.availability.unavailable': string;
+    'sourcePage.role': string;
+    'sourcePage.revision': string;
+    'sourcePage.permissions': string;
+    'sourcePage.diagnostics': string;
+    'sourcePage.configuration': string;
+    'sourcePage.configurationDescription': string;
+    'sourcePage.configLoading': string;
+    'sourcePage.configSave': string;
+    'sourcePage.configSaving': string;
+    'sourcePage.configSaved': string;
+    'sourcePage.secretPlaceholder': string;
+    'sourcePage.unavailable': string;
+    'sourcePage.unavailableDescription': string;
+    'telemetry.aria': string;
+    'telemetry.title': string;
+    'telemetry.memories': string;
+    'telemetry.graph': string;
+    'telemetry.entities': string;
+    'telemetry.spaces': string;
+    'sidebar.activeSpaces': string;
     'overview.title': string;
     'overview.description': string;
     'overview.pageDescription': string;
@@ -1570,6 +1644,16 @@ export declare const en: {
     'config.topologyEnabled': string;
     'config.topologyDisabled': string;
     'config.topologyLayerToggle': string;
+    'config.enhancementsTitle': string;
+    'config.enhancementsDescription': string;
+    'config.enhancementCapture': string;
+    'config.enhancementCaptureHint': string;
+    'config.enhancementLightContext': string;
+    'config.enhancementLightContextHint': string;
+    'config.enhancementScoped': string;
+    'config.enhancementScopedHint': string;
+    'config.enhancementsFailed': string;
+    'config.enhancementsRefreshFailed': string;
     'layers.runtimeLabel': string;
     'layers.runtimeDescription': string;
     'layers.documentsLabel': string;

package/lib/types/src/client/page-client.d.ts

@@ -0,0 +1,15 @@
+import type { JSX, ReactNode } from 'react';
+import type { MemoryJsonValue } from "../core/contracts/index.js";
+import type { MnemonSourceManagementClient } from './source-contracts.ts';
+/** Optional default presentation kit; custom pages may use their own UI. */
+export declare function MemorySourcePageFrame(props: {
+    locale: string;
+    children: ReactNode;
+}): JSX.Element;
+/** Track revisions returned by reads as well as writes; never retry a conflict. */
+export declare function createMemorySourcePageClient(management: MnemonSourceManagementClient): {
+    canAssist: (operation: string) => boolean;
+    assist: <T>(operation: string, input: MemoryJsonValue, confirmed: boolean) => Promise<T>;
+    read: <T>(operation: string, input?: MemoryJsonValue) => Promise<T>;
+    mutate: <T>(operation: string, input: MemoryJsonValue, confirmed: true) => Promise<T>;
+};

package/lib/types/src/client/page-kit.d.ts

@@ -0,0 +1,40 @@
+import type { JSX } from 'react';
+import { type MnemonTranslate } from './locales.ts';
+import { type MnemonDialogProps } from './MnemonDialog.tsx';
+export declare const I18nContext: import("react").Context<MnemonTranslate>;
+export declare const LocaleContext: import("react").Context<string>;
+export declare function useT(): MnemonTranslate;
+export declare function useLocale(): string;
+export declare function humanBytes(bytes: number): string;
+export declare function message(error: unknown): string;
+export declare function parseBranchesInput(raw: string): string[] | undefined;
+export declare function short(value: string, max: number): string;
+export declare function PageHeader(props: {
+    title: string;
+    description: string;
+    meta?: string;
+    loadingLabel?: string;
+    action?: JSX.Element;
+}): JSX.Element;
+export declare function PageSpinner({ label }: {
+    label: string;
+}): JSX.Element;
+export declare function SectionSpinner({ label }: {
+    label: string;
+}): JSX.Element;
+export declare function ProgressiveFooter(props: {
+    visible: number;
+    total: number;
+    pageSize: number;
+    compact?: boolean;
+    onMore: () => void;
+}): JSX.Element | null;
+/** DSH-style action dialog shared by Sidebar add/write flows. */
+export declare function SidebarModal(props: Omit<MnemonDialogProps, 'closeLabel'>): JSX.Element;
+export declare function EmptyState(props: {
+    glyph: string;
+    title: string;
+    children: string;
+}): JSX.Element;
+export declare const memoryPageStyles: Readonly<Record<string, string>>;
+export declare const memorySidebarStyles: Readonly<Record<string, string>>;

package/lib/types/src/client/source-contracts.d.ts

@@ -0,0 +1,46 @@
+import type { MemoryJsonValue, MemorySourceManagementInstance, MemorySourceManagementResult } from "../core/contracts/index.js";
+/** Instance- and scope-bound capability; never the Host's raw transport. */
+export interface MnemonSourceManagementClient {
+    readonly sourceInstanceKey: string;
+    readonly revision: string;
+    /** Optional workflows advertised and authorized by the Host for this exact instance. */
+    readonly assistance?: {
+        readonly operations: readonly string[];
+        execute(operation: string, input: MemoryJsonValue, options: {
+            expectedRevision: string;
+            confirmed: boolean;
+        }): Promise<MemorySourceManagementResult>;
+    };
+    read(operation: string, input?: MemoryJsonValue): Promise<MemorySourceManagementResult>;
+    mutate(operation: string, input: MemoryJsonValue, options: {
+        expectedRevision?: string;
+        confirmed: true;
+    }): Promise<MemorySourceManagementResult>;
+}
+/** Browser metadata is display-only; the Host validates capability identifiers. */
+export type MemorySourcePageInstance = Omit<MemorySourceManagementInstance, 'capabilities'> & {
+    capabilities: readonly string[];
+};
+export interface MemorySourcePageProps {
+    /** Type-level presentation identity; never a Client or Host Fiber uid. */
+    sourceTypeId: string;
+    /** Selected Host instance in the current authenticated scope. */
+    sourceInstanceKey?: string;
+    sourceInstances: readonly MemorySourcePageInstance[];
+    /** Present only while the selected Host instance remains visible. */
+    management?: MnemonSourceManagementClient;
+    /** Presentation hint only; the Host still authenticates every mutation. */
+    writable?: boolean;
+    sessionId?: string;
+    workspaceId?: string;
+    locale: string;
+    /** Opaque navigation data owned by this Source page. */
+    navigationInput?: MemoryJsonValue;
+    onRefresh?(): void;
+    /** Optional, Source-bound product preferences; no raw settings service or secrets. */
+    preferences?: {
+        value: MemoryJsonValue;
+        writable: boolean;
+        replace(value: MemoryJsonValue): Promise<void>;
+    };
+}

package/lib/types/src/client/source-pages.d.ts

@@ -0,0 +1,83 @@
+import { type ReactNode } from 'react';
+import type { MemorySourcePageProps } from './source-contracts.ts';
+export type { MemorySourcePageProps } from './source-contracts.ts';
+export declare const MNEMON_SOURCE_PAGE_SLOT: "mnemon.source.page";
+/** Conventional operations used by Mnemon's descriptor-driven Source page. */
+export declare const MNEMON_SOURCE_CONFIGURATION_READ: "configuration";
+export declare const MNEMON_SOURCE_CONFIGURATION_MUTATE: "configuration";
+export type MemorySourcePageComponent = (props: MemorySourcePageProps) => ReactNode;
+/** The existing DSH Slot capability narrowed to this one child Slot. */
+export interface MemorySourceUIContext {
+    locale?: {
+        bind(namespace: 'mnemon'): import('./locales.ts').MnemonTranslate;
+    };
+    slots: {
+        inject(name: typeof MNEMON_SOURCE_PAGE_SLOT, setup: () => () => void): () => void;
+        register(options: {
+            name: typeof MNEMON_SOURCE_PAGE_SLOT;
+            id: string;
+            order: number;
+            label: string | (() => string);
+            priority?: number;
+        }, component: MemorySourcePageComponent): () => void;
+    };
+}
+interface MemorySourcePageDirectoryContext {
+    locale?: {
+        getSnapshot(): unknown;
+        subscribe(listener: () => void): () => void;
+    };
+    slots: {
+        getVersion(name: typeof MNEMON_SOURCE_PAGE_SLOT): number;
+        entriesOfSlot(name: typeof MNEMON_SOURCE_PAGE_SLOT): readonly {
+            options: {
+                id?: string;
+                label?: string | (() => string);
+                order?: number;
+            };
+            component?: unknown;
+        }[];
+        subscribe(name: typeof MNEMON_SOURCE_PAGE_SLOT, listener: () => void): () => void;
+    };
+}
+export interface MemorySourcePageNavigation {
+    /** Let the Host retain a compact page header while scrolling in a sidebar. */
+    stickyHeader?: boolean;
+    group?: 'storage' | 'tools' | 'sources';
+    primary?: boolean;
+    glyph?: string;
+    detail?: string | (() => string);
+}
+export interface MemorySourcePageDefinition {
+    id: string;
+    label: string | (() => string);
+    order?: number;
+    component: MemorySourcePageComponent;
+    navigation?: MemorySourcePageNavigation;
+}
+export interface MemorySourceUIContribution {
+    sourceTypeId: string;
+    pages: readonly MemorySourcePageDefinition[];
+}
+export interface MemorySourcePageEntry {
+    id: string;
+    sourceTypeId: string;
+    pageId: string;
+    label: string;
+    order: number;
+    navigation?: Omit<MemorySourcePageNavigation, 'detail'> & {
+        detail?: string;
+    };
+}
+export interface MemorySourcePageDirectory {
+    getSnapshot(): readonly MemorySourcePageEntry[];
+    subscribe(listener: () => void): () => void;
+}
+export declare function memorySourcePageEntryId(sourceTypeId: string, pageId: string): string;
+/**
+ * Thin Client-Fiber adapter over the DSH child Slot. It creates no service or
+ * registry: `slots.inject/register` own declaration waiting and disposal.
+ */
+export declare function installMemorySourceUI(ctx: MemorySourceUIContext, contribution: MemorySourceUIContribution): () => void;
+/** Stable uSES directory over the Slot ledger; no parallel page registry. */
+export declare function createMemorySourcePageDirectory(ctx: MemorySourcePageDirectoryContext): MemorySourcePageDirectory;

package/lib/types/src/core/contracts/index.d.ts

@@ -0,0 +1,40 @@
+/** Metadata, operation inputs and protocol results use JSON-safe values. */
+export type MemoryJsonPrimitive = string | number | boolean | null;
+export type MemoryJsonValue = MemoryJsonPrimitive | MemoryJsonValue[] | {
+    [key: string]: MemoryJsonValue;
+};
+export declare const MEMORY_CAPABILITIES: readonly ["status", "project", "recall", "search", "read", "browse", "write", "archive", "graph", "related", "link", "forget", "maintain", "export", "import"];
+export type MemoryCapability = typeof MEMORY_CAPABILITIES[number];
+export interface MemoryOperationScope {
+    storage: 'global' | 'workspace' | 'custom';
+    workspaceId?: string;
+    sessionId?: string;
+    agentId?: string;
+}
+export type MemoryReceiptStatus = 'succeeded' | 'partial' | 'failed' | 'cancelled';
+export interface MemoryMigrationLineageEndpoint {
+    layerId: string;
+    reference: string;
+    digest: string;
+}
+/** Auditable proof that one exact source item reached one committed destination. */
+export interface MemoryMigrationLineage {
+    source: MemoryMigrationLineageEndpoint;
+    destination: MemoryMigrationLineageEndpoint;
+}
+export declare const MEMORY_SOURCE_MODES: readonly ["eager", "routed"];
+export type MemorySourceMode = typeof MEMORY_SOURCE_MODES[number];
+export interface MemoryWakeSection {
+    layerId: string;
+    mode: MemorySourceMode;
+    text: string;
+}
+export interface MemoryWake {
+    viewId: string;
+    viewDigest: string;
+    text: string;
+    sections: MemoryWakeSection[];
+    guidance?: import('./view.ts').MemoryViewGuidance;
+}
+export * from './plugin.ts';
+export * from './view.ts';

package/lib/types/src/core/contracts/plugin.d.ts

@@ -0,0 +1,32 @@
+/** Declarative identity and graph relations shared by every Mnemon plugin. */
+export declare const MEMORY_PLUGIN_API_VERSION: "dsh-mnemon/plugin/v1";
+export type MemoryPluginRole = 'source' | 'strategy' | 'strategy-extension';
+export interface MemoryPluginLocalizedText {
+    en: string;
+    'zh-CN': string;
+}
+/**
+ * A capability is a graph edge, not a runtime permission. Multiple plugins may
+ * provide the same capability unless the capability is explicitly exclusive.
+ */
+export interface MemoryPluginProvidedCapability {
+    id: string;
+    exclusive?: true;
+}
+/**
+ * JSON-safe module export named `memoryPlugin`.
+ *
+ * Source and Strategy are contribution roles of one peer plugin model. The
+ * descriptor is available before activation, so a Host can explain and verify
+ * dependencies without executing the plugin. Core remains the sole View
+ * compiler; a plugin never publishes a View directly.
+ */
+export interface MemoryPluginDescriptor {
+    apiVersion: typeof MEMORY_PLUGIN_API_VERSION;
+    packageName: string;
+    label: MemoryPluginLocalizedText;
+    description: MemoryPluginLocalizedText;
+    roles: MemoryPluginRole[];
+    provides: MemoryPluginProvidedCapability[];
+    requires?: string[];
+}