dsh-mnemon 0.2.15 → 0.3.0

package/lib/strategy-default-three-tier.js

@@ -0,0 +1,99 @@
+import { RUNTIME_MEMORY_LAYER } from "./layers/runtime.js";
+import { DOCUMENTS_MEMORY_LAYER } from "./layers/documents.js";
+import { MEMORY_SPACES_LAYER } from "./layers/memory-spaces.js";
+import { participationChannel } from "./kernel.js";
+//#region packages/strategy-default-three-tier/src/index.ts
+const BUILTIN_MEMORY_LAYERS = [
+	RUNTIME_MEMORY_LAYER,
+	DOCUMENTS_MEMORY_LAYER,
+	MEMORY_SPACES_LAYER
+];
+const DEFAULT_LAYER_PARTICIPATION = Object.freeze({
+	recall: "automatic",
+	write: "automatic",
+	projection: "automatic",
+	maintenance: "automatic"
+});
+function topologyLayer(id) {
+	return {
+		id,
+		enabled: true,
+		participation: { ...DEFAULT_LAYER_PARTICIPATION },
+		adapterIds: []
+	};
+}
+const DEFAULT_THREE_TIER_TOPOLOGY = Object.freeze({
+	id: "default-three-tier",
+	strategyId: "default-three-tier",
+	layers: Object.freeze([
+		topologyLayer("runtime"),
+		topologyLayer("documents"),
+		topologyLayer("memory-spaces")
+	])
+});
+function accepts(layer, request) {
+	if (!layer.enabled) return false;
+	const mode = layer.participation[participationChannel(request.capability)];
+	if (mode === "off") return false;
+	if (request.trigger !== "manual" && mode !== "automatic") return false;
+	return true;
+}
+const DEFAULT_THREE_TIER_STRATEGY = {
+	descriptor: {
+		id: "default-three-tier",
+		version: "1",
+		label: "Default three-tier strategy",
+		description: "Routes explicit operations to compatible enabled layers in stable topology order.",
+		hooks: [
+			"placement",
+			"retrieval-planning",
+			"projection",
+			"maintenance"
+		],
+		deterministic: true
+	},
+	propose(request, context) {
+		const candidates = request.candidateLayerIds === void 0 ? void 0 : new Set(request.candidateLayerIds);
+		const adapters = request.adapterIds === void 0 ? void 0 : new Set(request.adapterIds);
+		const descriptors = new Map(context.catalog.layers.map((layer) => [layer.id, layer]));
+		const steps = [];
+		for (const layer of context.topology.layers) {
+			const descriptor = descriptors.get(layer.id);
+			if (descriptor === void 0 || !descriptor.capabilities.includes(request.capability)) continue;
+			if (candidates !== void 0 && !candidates.has(layer.id)) continue;
+			if (!accepts(layer, request)) continue;
+			const selectedAdapters = adapters === void 0 ? layer.adapterIds : layer.adapterIds.filter((id) => adapters.has(id));
+			if (selectedAdapters.length === 0) steps.push({
+				layerId: layer.id,
+				capability: request.capability,
+				...request.input === void 0 ? {} : { input: request.input }
+			});
+			else steps.push(...selectedAdapters.map((adapterId) => ({
+				layerId: layer.id,
+				adapterId,
+				capability: request.capability,
+				...request.input === void 0 ? {} : { input: request.input }
+			})));
+		}
+		return {
+			strategyId: this.descriptor.id,
+			strategyVersion: this.descriptor.version,
+			reason: steps.length === 0 ? `No enabled layer accepts ${request.capability} for a ${request.trigger} operation.` : `Selected ${steps.length} compatible step${steps.length === 1 ? "" : "s"} from the active three-tier topology.`,
+			steps
+		};
+	}
+};
+function registerDefaultMemorySystem(catalog, layers = {}) {
+	const disposers = [...BUILTIN_MEMORY_LAYERS.map((descriptor) => catalog.registerLayer({
+		descriptor: {
+			...descriptor,
+			capabilities: [...descriptor.capabilities]
+		},
+		...layers[descriptor.id]
+	})), catalog.registerStrategy(DEFAULT_THREE_TIER_STRATEGY)];
+	return () => {
+		for (const dispose of disposers.reverse()) dispose();
+	};
+}
+//#endregion
+export { BUILTIN_MEMORY_LAYERS, DEFAULT_LAYER_PARTICIPATION, DEFAULT_THREE_TIER_STRATEGY, DEFAULT_THREE_TIER_TOPOLOGY, registerDefaultMemorySystem };

package/lib/strategy-sdk.js

@@ -0,0 +1,56 @@
+//#region packages/strategy-sdk/src/index.ts
+const MEMORY_STRATEGY_PLUGIN_API_VERSION = "dsh-mnemon/v1alpha1";
+/** Define an immutable, declarative strategy package; the Kernel remains authoritative. */
+function defineMemoryStrategyPlugin(plugin) {
+	if (plugin.manifest.apiVersion !== "dsh-mnemon/v1alpha1") throw new Error(`unsupported memory strategy plugin API: ${plugin.manifest.apiVersion}`);
+	if (plugin.manifest.kind !== "MemoryStrategyPlugin") throw new Error("memory strategy plugin kind must be MemoryStrategyPlugin");
+	if (plugin.manifest.metadata.id !== plugin.strategy.descriptor.id || plugin.manifest.metadata.version !== plugin.strategy.descriptor.version) throw new Error("memory strategy plugin manifest does not match its strategy identity");
+	if (!Number.isInteger(plugin.manifest.permissions.maxSteps) || plugin.manifest.permissions.maxSteps < 1 || plugin.manifest.permissions.maxSteps > 100) throw new Error("memory strategy plugin maxSteps must be an integer within 1..100");
+	const manifest = Object.freeze({
+		...plugin.manifest,
+		metadata: Object.freeze({ ...plugin.manifest.metadata }),
+		permissions: Object.freeze({
+			...plugin.manifest.permissions,
+			layerIds: Object.freeze([...new Set(plugin.manifest.permissions.layerIds)]),
+			adapterIds: Object.freeze([...new Set(plugin.manifest.permissions.adapterIds)]),
+			capabilities: Object.freeze([...new Set(plugin.manifest.permissions.capabilities)])
+		})
+	});
+	const allowedLayers = new Set(manifest.permissions.layerIds);
+	const allowedAdapters = new Set(manifest.permissions.adapterIds);
+	const allowedCapabilities = new Set(manifest.permissions.capabilities);
+	const propose = plugin.strategy.propose.bind(plugin.strategy);
+	const strategy = Object.freeze({
+		descriptor: Object.freeze({
+			...plugin.strategy.descriptor,
+			hooks: Object.freeze([...plugin.strategy.descriptor.hooks])
+		}),
+		async propose(request, context) {
+			if (!allowedCapabilities.has(request.capability)) throw new Error(`memory strategy plugin is not permitted to use ${request.capability}`);
+			const proposal = await propose(request, context);
+			if (proposal.steps.length > manifest.permissions.maxSteps) throw new Error(`memory strategy plugin proposed ${proposal.steps.length} steps; manifest allows ${manifest.permissions.maxSteps}`);
+			for (const step of proposal.steps) {
+				if (!allowedLayers.has(step.layerId)) throw new Error(`memory strategy plugin is not permitted to use layer ${step.layerId}`);
+				if (!allowedCapabilities.has(step.capability)) throw new Error(`memory strategy plugin is not permitted to use ${step.capability}`);
+				if (step.adapterId !== void 0 && !allowedAdapters.has(step.adapterId)) throw new Error(`memory strategy plugin is not permitted to use adapter ${step.adapterId}`);
+			}
+			return proposal;
+		}
+	});
+	return Object.freeze({
+		manifest,
+		strategy
+	});
+}
+/** Deterministic replay primitive for generated and hand-written strategies. */
+async function replayMemoryStrategy(strategy, cases) {
+	for (const replay of cases) {
+		const proposal = await strategy.propose(replay.request, replay.descriptor);
+		await replay.assert(proposal);
+	}
+}
+function defineMemoryStrategy(strategy) {
+	return strategy;
+}
+//#endregion
+export { MEMORY_STRATEGY_PLUGIN_API_VERSION, defineMemoryStrategy, defineMemoryStrategyPlugin, replayMemoryStrategy };

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

@@ -0,0 +1,221 @@
+/** JSON values are the only values allowed to cross a Mnemon plugin boundary. */
+export type MemoryJsonPrimitive = string | number | boolean | null;
+export type MemoryJsonValue = MemoryJsonPrimitive | MemoryJsonValue[] | {
+    [key: string]: MemoryJsonValue;
+};
+export declare const BUILTIN_MEMORY_LAYER_IDS: readonly ["runtime", "documents", "memory-spaces"];
+export type BuiltinMemoryLayerId = typeof BUILTIN_MEMORY_LAYER_IDS[number];
+export type MemoryLayerId = string;
+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 declare const MEMORY_STRATEGY_HOOKS: readonly ["admission", "placement", "retrieval-planning", "quality-fusion", "projection", "promotion-demotion", "retention", "maintenance"];
+export type MemoryStrategyHook = typeof MEMORY_STRATEGY_HOOKS[number];
+export type MemoryParticipationMode = 'off' | 'manual' | 'automatic';
+export type MemoryParticipationChannel = 'recall' | 'write' | 'projection' | 'maintenance';
+export interface MemoryLayerParticipation {
+    recall: MemoryParticipationMode;
+    write: MemoryParticipationMode;
+    projection: MemoryParticipationMode;
+    maintenance: MemoryParticipationMode;
+}
+export interface MemoryLayerDescriptor {
+    id: MemoryLayerId;
+    label: string;
+    description: string;
+    /** Stable semantic role. Several implementations may eventually satisfy one role. */
+    role: string;
+    order: number;
+    capabilities: MemoryCapability[];
+}
+export type MemoryAdapterLocality = 'local' | 'remote' | 'hybrid';
+export type MemoryAdapterScope = 'global' | 'workspace' | 'custom' | 'provider-owned';
+export interface MemoryAdapterDescriptor {
+    id: string;
+    label: string;
+    description: string;
+    locality: MemoryAdapterLocality;
+    scopes: MemoryAdapterScope[];
+    capabilities: MemoryCapability[];
+    configNamespace?: string;
+}
+export interface MemoryStrategyDescriptor {
+    id: string;
+    version: string;
+    label: string;
+    description: string;
+    hooks: MemoryStrategyHook[];
+    deterministic: boolean;
+}
+export interface MemoryCatalogSnapshot {
+    generation: number;
+    layers: MemoryLayerDescriptor[];
+    adapters: MemoryAdapterDescriptor[];
+    strategies: MemoryStrategyDescriptor[];
+}
+export interface MemoryTopologyLayer {
+    id: MemoryLayerId;
+    enabled: boolean;
+    participation: MemoryLayerParticipation;
+    adapterIds: string[];
+}
+export interface MemoryTopologyDefinition {
+    id: string;
+    strategyId: string;
+    layers: MemoryTopologyLayer[];
+}
+export interface MemoryTopologySnapshot extends MemoryTopologyDefinition {
+    generation: number;
+    catalogGeneration: number;
+    createdAt: string;
+}
+export type MemoryOperationTrigger = 'manual' | 'automatic' | 'system';
+export interface MemoryOperationScope {
+    storage: 'global' | 'workspace' | 'custom';
+    workspaceId?: string;
+    sessionId?: string;
+    agentId?: string;
+}
+export interface MemoryOperationBudget {
+    maxSteps?: number;
+    maxResults?: number;
+    maxTokens?: number;
+    timeoutMs?: number;
+}
+export interface MemoryPlanRequest {
+    operation: string;
+    capability: MemoryCapability;
+    trigger: MemoryOperationTrigger;
+    scope: MemoryOperationScope;
+    candidateLayerIds?: MemoryLayerId[];
+    adapterIds?: string[];
+    budget?: MemoryOperationBudget;
+    input?: MemoryJsonValue;
+}
+export interface MemoryPlanStepProposal {
+    layerId: MemoryLayerId;
+    capability: MemoryCapability;
+    adapterId?: string;
+    input?: MemoryJsonValue;
+}
+export interface MemoryPlanProposal {
+    strategyId: string;
+    strategyVersion: string;
+    reason: string;
+    steps: MemoryPlanStepProposal[];
+}
+export interface MemoryPlanStep extends MemoryPlanStepProposal {
+    id: string;
+    participation: MemoryParticipationChannel;
+}
+export interface MemoryPlan {
+    id: string;
+    topologyId: string;
+    topologyGeneration: number;
+    catalogGeneration: number;
+    guardGeneration: number;
+    strategyId: string;
+    strategyVersion: string;
+    operation: string;
+    capability: MemoryCapability;
+    trigger: MemoryOperationTrigger;
+    scope: MemoryOperationScope;
+    /** Canonical JSON request approved by Guards and proposed against by the Strategy. */
+    request: MemoryPlanRequest;
+    /** SHA-256 of the canonical request, used to bind execution to that exact request. */
+    requestDigest: string;
+    reason: string;
+    createdAt: string;
+    budget: MemoryOperationBudget;
+    steps: MemoryPlanStep[];
+}
+export type MemoryGuardDecision = {
+    kind: 'allow';
+} | {
+    kind: 'deny';
+    reason: string;
+};
+export type MemoryReceiptStatus = 'succeeded' | 'partial' | 'failed' | 'cancelled';
+export type MemoryReceiptStepStatus = 'succeeded' | 'failed' | 'cancelled';
+export interface MemoryReceiptStep {
+    stepId: string;
+    layerId: MemoryLayerId;
+    adapterId?: string;
+    status: MemoryReceiptStepStatus;
+    startedAt: string;
+    finishedAt: string;
+    output?: MemoryJsonValue;
+    error?: string;
+}
+export interface MemoryReceipt {
+    id: string;
+    planId: string;
+    topologyId: string;
+    topologyGeneration: number;
+    catalogGeneration: number;
+    guardGeneration: number;
+    strategyId: string;
+    strategyVersion: string;
+    operation: string;
+    capability: MemoryCapability;
+    status: MemoryReceiptStatus;
+    startedAt: string;
+    finishedAt: string;
+    steps: MemoryReceiptStep[];
+}
+export interface MemoryMigrationLineageEndpoint {
+    layerId: MemoryLayerId;
+    reference: string;
+    digest: string;
+}
+/** Auditable proof that one exact source item reached one committed destination. */
+export interface MemoryMigrationLineage {
+    source: MemoryMigrationLineageEndpoint;
+    destination: MemoryMigrationLineageEndpoint;
+}
+export interface MemorySystemDescriptor {
+    catalog: MemoryCatalogSnapshot;
+    topology: MemoryTopologySnapshot;
+}
+export declare const MEMORY_SOURCE_MODES: readonly ["eager", "routed"];
+export type MemorySourceMode = typeof MEMORY_SOURCE_MODES[number];
+export interface MemoryTurnViewSource {
+    layerId: MemoryLayerId;
+    revision: string;
+    mode: MemorySourceMode;
+    digest: string;
+    /** Exact eager content or one compact routed cover; never a child catalog. */
+    wake: string;
+}
+/** Immutable Source-generation snapshot pinned by one or more user turns. */
+export interface MemoryTurnView {
+    id: string;
+    createdAt: string;
+    topologyId: string;
+    catalogGeneration: number;
+    topologyGeneration: number;
+    guardGeneration: number;
+    sources: MemoryTurnViewSource[];
+    digest: string;
+}
+/** Compatibility name for the v0.3 pre-release API. */
+export type MemoryView = MemoryTurnView;
+/** Compatibility name for the v0.3 pre-release API. */
+export type MemoryViewSource = MemoryTurnViewSource;
+export interface MemoryWakeSection {
+    layerId: MemoryLayerId;
+    mode: MemorySourceMode;
+    text: string;
+}
+export interface MemoryWake {
+    viewId: string;
+    viewDigest: string;
+    text: string;
+    sections: MemoryWakeSection[];
+}
+export interface MemoryTurnContext {
+    turnId: string;
+    viewId: string;
+    viewDigest: string;
+    scope: MemoryOperationScope;
+    startedAt: string;
+}

package/lib/types/packages/extension-sdk/src/index.d.ts

@@ -0,0 +1,54 @@
+import type { MemoryAdapterRegistration, MemoryCatalog, MemoryLayerRegistration, MemoryStrategyRegistration } from '../../kernel/src/catalog.ts';
+import type { MemoryGuardRegistration, MemoryKernel } from '../../kernel/src/kernel.ts';
+import type { MemorySource, MemoryTurnViewManager } from '../../kernel/src/view.ts';
+export interface MemoryExtensionDescriptor {
+    id: string;
+    version: string;
+    label: string;
+    description: string;
+}
+export interface MemoryExtension {
+    descriptor: MemoryExtensionDescriptor;
+    layers?: readonly MemoryLayerRegistration[];
+    adapters?: readonly MemoryAdapterRegistration[];
+    strategies?: readonly MemoryStrategyRegistration[];
+    /** Trusted, query-independent Sources for extension Layers. */
+    sources?: readonly MemorySource[];
+    /** Guards can only deny; strategies and data-plane executors cannot bypass them. */
+    guards?: readonly MemoryGuardRegistration[];
+}
+export interface MemoryBootAttachment {
+    bindKernel(kernel: MemoryKernel): void;
+    bindTurnViews(manager: MemoryTurnViewManager): void;
+    dispose(): void;
+    release(): void;
+}
+/** Compatibility name for the v0.3 pre-release API. */
+export type MemoryExtensionAttachment = MemoryBootAttachment;
+/**
+ * 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.
+ */
+export declare class MemoryBoot {
+    private readonly extensions;
+    private readonly targets;
+    register(extension: MemoryExtension): () => void;
+    attach(catalog: MemoryCatalog): MemoryBootAttachment;
+    descriptors(): MemoryExtensionDescriptor[];
+    private apply;
+    private applyChecked;
+    /** Remove one global extension from every live graph, or restore it everywhere. */
+    private unregister;
+}
+/** Compatibility name for the v0.3 pre-release API. */
+export { MemoryBoot as MemoryExtensionHost };
+export declare function defineMemoryExtension<T extends MemoryExtension>(extension: T): T;
+/** Process-global Boot, allowing extensions to contribute before the DSH Host mounts. */
+export declare const memoryBoot: MemoryBoot;
+/** Compatibility name for the v0.3 pre-release API. */
+export declare const memoryExtensions: MemoryBoot;
+export declare function registerMemoryExtension(extension: MemoryExtension): () => void;
+export type { MemoryAdapterRegistration, MemoryLayerRegistration, MemoryStrategyRegistration } from '../../kernel/src/catalog.ts';
+export type { MemoryGuardRegistration } from '../../kernel/src/kernel.ts';
+export type { MemorySource } from '../../kernel/src/view.ts';

package/lib/types/packages/kernel/src/access.d.ts

@@ -0,0 +1,14 @@
+import type { MemoryCapability, MemoryOperationTrigger, MemoryParticipationChannel, MemoryParticipationMode, MemoryTopologyLayer } from '../../contracts/src/index.ts';
+export declare function participationChannel(capability: MemoryCapability): MemoryParticipationChannel;
+export interface MemoryParticipationDecision {
+    allowed: boolean;
+    layerId: string;
+    capability: MemoryCapability;
+    trigger: MemoryOperationTrigger;
+    channel: MemoryParticipationChannel;
+    mode: MemoryParticipationMode;
+    reason?: string;
+}
+/** Evaluate one topology boundary without invoking strategy or data-plane code. */
+export declare function decideMemoryLayerParticipation(layer: MemoryTopologyLayer, capability: MemoryCapability, trigger: MemoryOperationTrigger): MemoryParticipationDecision;
+export declare function assertMemoryLayerParticipation(layer: MemoryTopologyLayer, capability: MemoryCapability, trigger: MemoryOperationTrigger): MemoryParticipationDecision;

package/lib/types/packages/kernel/src/catalog.d.ts

@@ -0,0 +1,42 @@
+import type { MemoryAdapterDescriptor, MemoryCatalogSnapshot, MemoryJsonValue, MemoryLayerDescriptor, MemoryPlanRequest, MemoryPlanProposal, MemoryPlanStep, MemoryStrategyDescriptor, MemoryTopologySnapshot } from '../../contracts/src/index.ts';
+export interface MemoryLayerExecutionContext {
+    planId: string;
+    topology: MemoryTopologySnapshot;
+    request: MemoryPlanRequest;
+    signal?: AbortSignal;
+}
+export interface MemoryLayerRegistration {
+    descriptor: MemoryLayerDescriptor;
+    execute?(step: MemoryPlanStep, context: MemoryLayerExecutionContext): Promise<MemoryJsonValue>;
+}
+export interface MemoryAdapterRegistration {
+    descriptor: MemoryAdapterDescriptor;
+}
+export interface MemoryStrategyContext {
+    catalog: MemoryCatalogSnapshot;
+    topology: MemoryTopologySnapshot;
+}
+export interface MemoryStrategyRegistration {
+    descriptor: MemoryStrategyDescriptor;
+    propose(request: MemoryPlanRequest, context: MemoryStrategyContext): MemoryPlanProposal | Promise<MemoryPlanProposal>;
+}
+export type MemoryCatalogListener = (snapshot: MemoryCatalogSnapshot) => void;
+/** Host-global contribution directory. Registrations are owned by their caller's lifecycle. */
+export declare class MemoryCatalog {
+    private readonly layers;
+    private readonly adapters;
+    private readonly strategies;
+    private readonly listeners;
+    private currentGeneration;
+    get generation(): number;
+    registerLayer(registration: MemoryLayerRegistration): () => void;
+    registerAdapter(registration: MemoryAdapterRegistration): () => void;
+    registerStrategy(registration: MemoryStrategyRegistration): () => void;
+    layer(id: string): MemoryLayerRegistration | undefined;
+    adapter(id: string): MemoryAdapterRegistration | undefined;
+    strategy(id: string): MemoryStrategyRegistration | undefined;
+    snapshot(): MemoryCatalogSnapshot;
+    subscribe(listener: MemoryCatalogListener): () => void;
+    private register;
+    private changed;
+}

package/lib/types/packages/kernel/src/index.d.ts

@@ -0,0 +1,5 @@
+export * from './access.ts';
+export * from './catalog.ts';
+export * from './kernel.ts';
+export * from './topology.ts';
+export * from './view.ts';

package/lib/types/packages/kernel/src/kernel.d.ts

@@ -0,0 +1,46 @@
+import type { MemoryCatalog } from './catalog.ts';
+import type { MemoryCapability, MemoryGuardDecision, MemoryOperationTrigger, MemoryPlan, MemoryPlanRequest, MemoryReceipt, MemorySystemDescriptor } from '../../contracts/src/index.ts';
+import { type MemoryParticipationDecision } from './access.ts';
+import type { MemoryTopologyManager } from './topology.ts';
+export interface MemoryGuardContext {
+    descriptor: MemorySystemDescriptor;
+}
+export interface MemoryGuardRegistration {
+    id: string;
+    decide(request: MemoryPlanRequest, context: MemoryGuardContext): MemoryGuardDecision | Promise<MemoryGuardDecision>;
+}
+export interface MemoryReceiptSink {
+    append(receipt: MemoryReceipt): void | Promise<void>;
+}
+export interface MemoryKernelOptions {
+    now?: () => Date;
+    id?: () => string;
+    receiptSink?: MemoryReceiptSink;
+}
+/** Plans and executes bounded operations without granting strategies direct data-plane access. */
+export declare class MemoryKernel {
+    readonly catalog: MemoryCatalog;
+    readonly topology: MemoryTopologyManager;
+    private readonly guards;
+    private currentGuardGeneration;
+    private readonly now;
+    private readonly id;
+    private readonly receiptSinks;
+    private readonly issuedPlans;
+    constructor(catalog: MemoryCatalog, topology: MemoryTopologyManager, options?: MemoryKernelOptions);
+    get guardGeneration(): number;
+    registerReceiptSink(sink: MemoryReceiptSink): () => void;
+    descriptor(): MemorySystemDescriptor;
+    participation(layerId: string, capability: MemoryCapability, trigger: MemoryOperationTrigger): MemoryParticipationDecision;
+    allows(layerId: string, capability: MemoryCapability, trigger: MemoryOperationTrigger): boolean;
+    assertParticipation(layerId: string, capability: MemoryCapability, trigger: MemoryOperationTrigger): MemoryParticipationDecision;
+    registerGuard(guard: MemoryGuardRegistration): () => void;
+    plan(request: MemoryPlanRequest): Promise<MemoryPlan>;
+    execute(plan: MemoryPlan, request: MemoryPlanRequest, signal?: AbortSignal): Promise<MemoryReceipt>;
+    run(request: MemoryPlanRequest, signal?: AbortSignal): Promise<{
+        plan: MemoryPlan;
+        receipt: MemoryReceipt;
+    }>;
+    private validateStep;
+    private rememberPlan;
+}

package/lib/types/packages/kernel/src/topology.d.ts

@@ -0,0 +1,25 @@
+import type { MemoryCatalog } from './catalog.ts';
+import type { MemoryLayerParticipation, MemoryTopologyDefinition, MemoryTopologySnapshot } from '../../contracts/src/index.ts';
+export type MemoryTopologyListener = (next: MemoryTopologySnapshot, previous: MemoryTopologySnapshot | undefined) => void;
+/** Atomic, versioned topology state. Per-operation callers pin one returned snapshot. */
+export declare class MemoryTopologyManager {
+    private readonly catalog;
+    private readonly now;
+    private current?;
+    private currentGeneration;
+    private readonly listeners;
+    private readonly unsubscribeCatalog;
+    constructor(catalog: MemoryCatalog, initial: MemoryTopologyDefinition, now?: () => Date);
+    snapshot(): MemoryTopologySnapshot;
+    replace(definition: MemoryTopologyDefinition): MemoryTopologySnapshot;
+    configureLayer(id: string, patch: {
+        enabled?: boolean;
+        participation?: Partial<MemoryLayerParticipation>;
+        adapterIds?: string[];
+    }): MemoryTopologySnapshot;
+    subscribe(listener: MemoryTopologyListener): () => void;
+    /** Stop following Catalog changes while preserving this generation for pinned operations. */
+    dispose(): void;
+    private reconcileCatalog;
+    private validate;
+}

package/lib/types/packages/kernel/src/view.d.ts

@@ -0,0 +1,78 @@
+import type { MemoryJsonValue, MemoryOperationScope, MemoryReceipt, MemorySourceMode, MemoryTurnContext, MemoryTurnView, MemoryWake } from '../../contracts/src/index.ts';
+import type { MemoryKernel } from './kernel.ts';
+export interface MemorySourceSnapshot {
+    /** Changes whenever the source's recall authority or Wake projection changes. */
+    revision: string;
+    /** Exact eager content or one compact routed cover. */
+    wake: string;
+    /** Host-only JSON authority. It is digest-bound and never rendered into Wake. */
+    state?: MemoryJsonValue;
+}
+export interface MemorySourceContext {
+    catalogGeneration: number;
+    topologyGeneration: number;
+    guardGeneration: number;
+    scope?: MemoryOperationScope;
+}
+/** Trusted source adapter. It snapshots authority without receiving a Strategy. */
+export interface MemorySource {
+    layerId: string;
+    mode: MemorySourceMode;
+    snapshot(context: MemorySourceContext): MemorySourceSnapshot | Promise<MemorySourceSnapshot>;
+}
+export interface MemoryTurnViewManagerOptions {
+    now?: () => Date;
+    maxViews?: number;
+    maxWakeCharacters?: number;
+    maxCoverCharacters?: number;
+}
+/** Compatibility name for the v0.3 pre-release API. */
+export type MemoryViewManagerOptions = MemoryTurnViewManagerOptions;
+/**
+ * Owns immutable Source snapshots and turn pins. Source state is Host-only;
+ * Wake is a separately budgeted projection and never defines recall authority.
+ */
+export declare class MemoryTurnViewManager {
+    readonly kernel: Pick<MemoryKernel, 'descriptor' | 'guardGeneration'>;
+    private readonly sources;
+    private sourceGeneration;
+    private readonly views;
+    private readonly turns;
+    private readonly pendingReceipts;
+    private current;
+    private readonly currentByScope;
+    private readonly publishing;
+    private failure;
+    private readonly now;
+    private readonly maxViews;
+    private readonly maxWakeCharacters;
+    private readonly maxCoverCharacters;
+    constructor(kernel: Pick<MemoryKernel, 'descriptor' | 'guardGeneration'>, sources?: Iterable<MemorySource>, options?: MemoryTurnViewManagerOptions);
+    registerSource(source: MemorySource): () => void;
+    /** Validate every automatic project-capable Layer before a runtime graph becomes live. */
+    assertSourcesReady(): void;
+    latest(): MemoryTurnView | undefined;
+    get(viewId: string): MemoryTurnView | undefined;
+    /** Read digest-bound recall authority. This state is never rendered into Wake. */
+    sourceState(viewId: string, layerId: string): MemoryJsonValue | undefined;
+    lastFailure(): string | undefined;
+    pendingReceiptCount(): number;
+    apply(receipt: MemoryReceipt): boolean;
+    beginTurn(turnId: string, scope: MemoryOperationScope): Promise<MemoryTurnContext>;
+    turn(turnId: string): MemoryTurnContext | undefined;
+    activeTurn(agentId: string): MemoryTurnContext | undefined;
+    endTurn(turnId: string): boolean;
+    wake(viewId: string): MemoryWake;
+    /** Compile and publish a candidate. On failure, preserve the last valid scoped View. */
+    reconcile(scope?: MemoryOperationScope): Promise<MemoryTurnView>;
+    /** Strict publication API used by tests, diagnostics, and initial startup. */
+    publish(scope?: MemoryOperationScope): Promise<MemoryTurnView>;
+    private buildCandidate;
+    private normalizeSource;
+    private renderWake;
+    private requireStoredView;
+    private rememberScopeCurrent;
+    private collect;
+}
+/** Compatibility name for the v0.3 pre-release API. */
+export { MemoryTurnViewManager as MemoryViewManager };

package/lib/types/packages/layer-documents/src/index.d.ts

@@ -0,0 +1,4 @@
+import type { MemoryLayerDescriptor } from '../../contracts/src/index.ts';
+import type { MemoryCatalog, MemoryLayerRegistration } from '../../kernel/src/index.ts';
+export declare const DOCUMENTS_MEMORY_LAYER: Readonly<MemoryLayerDescriptor>;
+export declare function registerDocumentsMemoryLayer(catalog: MemoryCatalog, registration?: Omit<MemoryLayerRegistration, 'descriptor'>): () => void;

package/lib/types/packages/layer-memory-spaces/src/index.d.ts

@@ -0,0 +1,4 @@
+import type { MemoryLayerDescriptor } from '../../contracts/src/index.ts';
+import type { MemoryCatalog, MemoryLayerRegistration } from '../../kernel/src/index.ts';
+export declare const MEMORY_SPACES_LAYER: Readonly<MemoryLayerDescriptor>;
+export declare function registerMemorySpacesLayer(catalog: MemoryCatalog, registration?: Omit<MemoryLayerRegistration, 'descriptor'>): () => void;

package/lib/types/packages/layer-runtime/src/index.d.ts

@@ -0,0 +1,4 @@
+import type { MemoryLayerDescriptor } from '../../contracts/src/index.ts';
+import type { MemoryCatalog, MemoryLayerRegistration } from '../../kernel/src/index.ts';
+export declare const RUNTIME_MEMORY_LAYER: Readonly<MemoryLayerDescriptor>;
+export declare function registerRuntimeMemoryLayer(catalog: MemoryCatalog, registration?: Omit<MemoryLayerRegistration, 'descriptor'>): () => void;