dsh-mnemon 0.4.7 → 0.5.0

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

@@ -0,0 +1,416 @@
+/**
+ * Public narrow waist for Composable View Memory plugins.
+ *
+ * Definitions contain executable factories and remain inside the Host realm.
+ * Every manifest, fact, spec, View, Evidence, and Receipt crossing that
+ * boundary is JSON-safe and can therefore be validated, digested, and replayed.
+ */
+import type { MemoryCapability, MemoryJsonValue, MemoryOperationScope, MemoryReceiptStatus, MemorySourceMode } from './index.ts';
+export declare const COMPOSABLE_MEMORY_API_VERSION: "dsh-mnemon/v1";
+/** Persistence truth, not a taxonomy of memory operations. */
+export type MemoryMutationCompletion = 'accepted' | 'candidate' | 'committed' | 'partial' | 'failed' | 'unknown';
+export type MemoryContributionKind = 'source' | 'strategy' | 'strategy-extension';
+export type MemorySourceAvailability = 'ready' | 'degraded' | 'unavailable';
+export type MemoryViewConsistencyMode = 'exact-snapshot' | 'namespace-pinned-live-read';
+export interface MemoryPackageProvenance {
+    /** npm package name or another stable artifact namespace. */
+    packageName: string;
+    /** Stable Loader Entry id (or an explicit id for direct ctx.plugin mounts). */
+    entryId: string;
+    /** Optional immutable package artifact digest supplied by an installer. */
+    artifactDigest?: string;
+}
+export interface MemoryManagementField {
+    key: string;
+    label: string;
+    description?: string;
+    input: 'text' | 'number' | 'boolean' | 'url' | 'secret' | 'select';
+    required: boolean;
+    secret?: boolean;
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+}
+/** JSON-safe presentation metadata. It never contains a React component. */
+export interface MemoryManagementDescriptor {
+    label: string;
+    description: string;
+    fields?: MemoryManagementField[];
+    diagnostics?: string[];
+}
+export type MemorySourceManagementMode = 'read' | 'mutate';
+/**
+ * Authenticated human-management request delivered to one Serving Source.
+ * It is deliberately separate from model Routes and ActionOffers: no View
+ * grant crosses into the browser management plane.
+ */
+export interface MemorySourceManagementRequest {
+    scope: MemoryOperationScope;
+    sourceInstanceKey: string;
+    mode: MemorySourceManagementMode;
+    operation: string;
+    input: MemoryJsonValue;
+    /** Mutations are revision-fenced by the caller and rechecked by the Source. */
+    expectedRevision?: string;
+    /** The Host only forwards mutations after an explicit confirmation. */
+    confirmed: boolean;
+    signal?: AbortSignal;
+}
+/** JSON-safe management projection or mutation result from one Source. */
+export interface MemorySourceManagementResult {
+    revision: string;
+    value: MemoryJsonValue;
+}
+/** Sanitized Source instance descriptor returned to authenticated clients. */
+export interface MemorySourceManagementInstance {
+    sourceInstanceKey: string;
+    sourceTypeId: string;
+    packageName: string;
+    role: string;
+    availability: MemorySourceAvailability;
+    revision: string;
+    capabilities: MemoryCapability[];
+    management: MemoryManagementDescriptor;
+    hints?: MemoryJsonValue;
+}
+export interface MemorySourceManagementCatalog {
+    generationId: string;
+    sources: MemorySourceManagementInstance[];
+    diagnostics?: MemoryCompositionDiagnostic[];
+}
+export interface MemorySourceRouteManifest {
+    /** Stable within one Source type. Runtime prefixes it with the instance key. */
+    id: string;
+    description: string;
+    capability: MemoryCapability;
+    inputSchema: MemoryJsonValue;
+    maxCalls: number;
+    maxResults?: number;
+    maxCharacters?: number;
+}
+export interface MemorySourceActionManifest {
+    /** Stable within one Source type. Runtime prefixes it with the instance key. */
+    id: string;
+    description: string;
+    capability: MemoryCapability;
+    inputSchema: MemoryJsonValue;
+    /** High-risk non-memory actions must name an external authority. */
+    authority?: string;
+}
+export interface MemorySourceManifest {
+    apiVersion: typeof COMPOSABLE_MEMORY_API_VERSION;
+    kind: 'source';
+    typeId: string;
+    packageName: string;
+    role: string;
+    capabilities: MemoryCapability[];
+    consistency: MemoryViewConsistencyMode;
+    routes?: MemorySourceRouteManifest[];
+    actions?: MemorySourceActionManifest[];
+    management?: MemoryManagementDescriptor;
+}
+export interface MemoryStrategyManifest {
+    apiVersion: typeof COMPOSABLE_MEMORY_API_VERSION;
+    kind: 'strategy';
+    typeId: string;
+    packageName: string;
+    deterministic: true;
+    supportedSourceRoles: string[];
+    maxSources: number;
+    maxRoutes: number;
+    maxActions: number;
+    /** Exclusive contribution slots owned by this Strategy, not Core vocabulary. */
+    extensionSlots?: string[];
+}
+/** An additive plugin targets one explicit Strategy contract, never replaces it. */
+export interface MemoryStrategyExtensionManifest {
+    apiVersion: typeof COMPOSABLE_MEMORY_API_VERSION;
+    kind: 'strategy-extension';
+    typeId: string;
+    packageName: string;
+    strategyTypeId: string;
+    slot: string;
+    deterministic: true;
+}
+export interface MemoryStrategyExtensionDefinition {
+    manifest: MemoryStrategyExtensionManifest;
+    /** Pure, bounded JSON proposal; no Source handles, write callbacks or credentials. */
+    contribute(request: MemoryViewRequest, sources: readonly MemoryAvailableSource[]): MemoryJsonValue;
+}
+/** The owning Strategy interprets value using its public, slot-specific contract. */
+export interface MemoryStrategyContribution {
+    instanceKey: string;
+    typeId: string;
+    slot: string;
+    value: MemoryJsonValue;
+}
+export interface MemorySourceFacts {
+    sourceInstanceKey: string;
+    sourceTypeId: string;
+    role: string;
+    availability: MemorySourceAvailability;
+    revision: string;
+    capabilities: MemoryCapability[];
+    routeIds: string[];
+    actionIds: string[];
+    /** Coarse, non-sensitive hints only; never raw Authority data or credentials. */
+    hints?: MemoryJsonValue;
+}
+export interface MemoryViewBudget {
+    maxProjectionCharacters: number;
+    maxRoutes: number;
+    maxActions: number;
+    maxEvidenceResults: number;
+    maxEvidenceCharacters: number;
+}
+/** Manifest operations filtered by live availability and Host permissions. */
+export interface MemoryAvailableSource extends MemorySourceFacts {
+    routes: MemorySourceRouteManifest[];
+    actions: MemorySourceActionManifest[];
+}
+export declare const DEFAULT_MEMORY_VIEW_BUDGET: Readonly<MemoryViewBudget>;
+export interface MemoryViewRequest {
+    scope: MemoryOperationScope;
+    scenario: string;
+    budget: MemoryViewBudget;
+}
+export interface MemoryViewSourceSpec {
+    sourceInstanceKey: string;
+    /** Defaults to true. An explicitly optional Source may be omitted on read failure. */
+    required?: boolean;
+    projection?: {
+        mode: MemorySourceMode;
+        maxCharacters: number;
+    };
+    /** Source-local route ids declared by its manifest/facts. */
+    routeIds?: string[];
+    /** Source-local action ids declared by its manifest/facts. */
+    actionIds?: string[];
+}
+/** Pure Strategy output. Runtime treats it as a proposal, never as authority. */
+export interface MemoryViewSpec {
+    strategyTypeId: string;
+    sources: MemoryViewSourceSpec[];
+    explanation: string;
+    /** Trusted Strategy instructions, separate from quoted Source data. */
+    guidance?: MemoryViewGuidance;
+}
+export interface MemoryViewGuidance {
+    system?: string;
+    routing?: string;
+    reminders?: {
+        read?: string;
+        write?: string;
+        both?: string;
+    };
+}
+export interface MemoryProjectionRequest {
+    scope: MemoryOperationScope;
+    sourceInstanceKey: string;
+    /** Facts revision selected by the Strategy; the Source owns its snapshot consistency. */
+    expectedRevision: string;
+    includeProjection: boolean;
+    mode: MemorySourceMode;
+    maxCharacters: number;
+}
+export interface MemoryViewFragment {
+    id: string;
+    sourceInstanceKey: string;
+    mode: MemorySourceMode;
+    text: string;
+    revision: string;
+    provenance?: MemoryJsonValue;
+}
+/**
+ * Bounded, Source-authored human presentation for one item in a View.
+ * It is descriptive only: Core never treats it as Evidence, authority, or
+ * model instructions, and the Host never renders executable UI from it.
+ */
+export interface MemorySourcePresentationItem {
+    id: string;
+    title: string;
+    excerpt?: string;
+}
+/**
+ * Optional browser-safe description of the items represented by a Source.
+ * `visibleItems` is the number in this View scope; `items` may be a bounded
+ * preview subset. `totalItems` may include inactive or out-of-scope items.
+ */
+export interface MemorySourcePresentation {
+    visibleItems: number;
+    totalItems?: number;
+    items?: MemorySourcePresentationItem[];
+}
+/** Source presentation after Core binds it to the selected mode and instance. */
+export interface MemoryViewSourcePresentation extends MemorySourcePresentation {
+    sourceInstanceKey: string;
+    mode: MemorySourceMode;
+}
+export interface MemoryReadGrant {
+    id: string;
+    sourceInstanceKey: string;
+    schema: string;
+    value: MemoryJsonValue;
+    revision: string;
+    consistency: MemoryViewConsistencyMode;
+}
+export interface MemoryViewContribution {
+    fragments: MemoryViewFragment[];
+    readGrant?: MemoryReadGrant;
+    /** Optional non-authoritative presentation; old Sources may omit it. */
+    presentation?: MemorySourcePresentation;
+}
+export interface MemoryViewRoute {
+    id: string;
+    sourceInstanceKey: string;
+    sourceRouteId: string;
+    description: string;
+    capability: MemoryCapability;
+    inputSchema: MemoryJsonValue;
+    readGrantId: string;
+    maxCalls: number;
+    maxResults?: number;
+    maxCharacters?: number;
+}
+export interface MemoryActionOffer {
+    id: string;
+    sourceInstanceKey: string;
+    sourceActionId: string;
+    description: string;
+    capability: MemoryCapability;
+    inputSchema: MemoryJsonValue;
+    authority?: string;
+}
+export interface MemoryViewConsistency {
+    mode: 'mixed' | MemoryViewConsistencyMode;
+    sourceRevisions: Record<string, string>;
+}
+/** Complete Host-side safety envelope. Read grants are never model-rendered. */
+export interface ComposableMemoryView {
+    id: string;
+    digest: string;
+    runtimeGeneration: string;
+    strategyInstanceKey: string;
+    strategyTypeId: string;
+    /** Auditable active contributions, without publishing their configuration to the LLM. */
+    strategyExtensions?: Array<{
+        instanceKey: string;
+        typeId: string;
+        slot: string;
+        digest: string;
+    }>;
+    createdAt: string;
+    scope: MemoryOperationScope;
+    projection: MemoryViewFragment[];
+    /** Optional Source-authored browser presentation; never model-rendered. */
+    sourcePresentations?: MemoryViewSourcePresentation[];
+    routes: MemoryViewRoute[];
+    readGrants: MemoryReadGrant[];
+    actionOffers: MemoryActionOffer[];
+    consistency: MemoryViewConsistency;
+    explanation: string;
+    guidance?: MemoryViewGuidance;
+    /** Sanitized, turn-local availability failures; never raw provider errors. */
+    diagnostics?: MemoryCompositionDiagnostic[];
+}
+export interface MemoryEvidenceItem {
+    id: string;
+    text: string;
+    provenance: MemoryJsonValue;
+    score?: number;
+    revision?: string;
+}
+export interface MemoryEvidence {
+    id: string;
+    viewId: string;
+    routeId: string;
+    sourceInstanceKey: string;
+    observedAt: string;
+    items: MemoryEvidenceItem[];
+    truncated: boolean;
+    unavailable?: string;
+    /** Source-owned read metadata; never authority or credentials. */
+    metadata?: MemoryJsonValue;
+    /** Strategy-owned model presentation. Host audit retains the evidence separately. */
+    output?: MemoryJsonValue;
+}
+export interface MemoryMutationReceipt {
+    id: string;
+    viewId: string;
+    offerId: string;
+    sourceInstanceKey: string;
+    status: MemoryReceiptStatus;
+    completion: MemoryMutationCompletion;
+    /** Only an explicitly confirmed commit may carry this timestamp. */
+    committedAt?: string;
+    revision?: string;
+    details?: MemoryJsonValue;
+}
+export interface MemorySourceRuntimeContext {
+    sourceInstanceKey: string;
+    provenance: MemoryPackageProvenance;
+    /** Immutable, JSON-only Host/scope defaults; never business objects or clients. */
+    configuration?: Readonly<Record<string, MemoryJsonValue>>;
+}
+/** Operation identity only; never the complete View or another Source's data. */
+export interface MemorySourceViewContext {
+    id: string;
+    scope: MemoryOperationScope;
+}
+export interface MemorySourceRuntime {
+    /** Lightweight metadata. Honor cancellation; do not perform writes here. */
+    facts(request: MemoryViewRequest, signal?: AbortSignal): MemorySourceFacts | Promise<MemorySourceFacts>;
+    project(request: MemoryProjectionRequest, signal?: AbortSignal): MemoryViewContribution | Promise<MemoryViewContribution>;
+    manage?(request: MemorySourceManagementRequest): MemorySourceManagementResult | Promise<MemorySourceManagementResult>;
+    query?(request: {
+        view: MemorySourceViewContext;
+        route: MemoryViewRoute;
+        grant: MemoryReadGrant;
+        input: MemoryJsonValue;
+        signal?: AbortSignal;
+    }): MemoryEvidence | Promise<MemoryEvidence>;
+    mutate?(request: {
+        view: MemorySourceViewContext;
+        offer: MemoryActionOffer;
+        /** This Source's own pinned read scope, when it contributed one. Not write authorization. */
+        grant?: MemoryReadGrant;
+        input: MemoryJsonValue;
+        signal?: AbortSignal;
+    }): MemoryMutationReceipt | Promise<MemoryMutationReceipt>;
+    dispose?(): void | Promise<void>;
+}
+export interface MemorySourceDefinition {
+    manifest: MemorySourceManifest;
+    create(context: MemorySourceRuntimeContext): MemorySourceRuntime;
+}
+export interface MemoryStrategyDefinition {
+    manifest: MemoryStrategyManifest;
+    compose(request: MemoryViewRequest, sources: readonly MemoryAvailableSource[], contributions?: readonly MemoryStrategyContribution[]): MemoryViewSpec;
+    /** Optional execution policy, instantiated once for each executing turn, never during compose. */
+    createTurn?(view: ComposableMemoryView): MemoryStrategyTurn;
+}
+export interface MemoryStrategyReadRequest {
+    route: MemoryViewRoute;
+    input: MemoryJsonValue;
+    signal?: AbortSignal;
+}
+export interface MemoryStrategyTurn {
+    /** The continuation can read only this offered Route, with the same grant and ceilings. */
+    query(request: MemoryStrategyReadRequest, read: MemoryStrategyRead): Promise<MemoryEvidence>;
+}
+export type MemoryStrategyRead = (input: MemoryJsonValue, limits?: Partial<Pick<MemoryViewRoute, 'maxResults' | 'maxCharacters'>>) => Promise<MemoryEvidence>;
+export interface MemoryCompositionDiagnostic {
+    code: string;
+    message: string;
+    contributionInstanceKey?: string;
+}
+export interface MemoryCompositionEvaluationReport {
+    state: 'ready' | 'incomplete' | 'rejected';
+    contributionRevision: number;
+    generationId?: string;
+    strategyInstanceKey?: string;
+    strategyExtensionInstanceKeys?: string[];
+    sourceInstanceKeys: string[];
+    diagnostics: MemoryCompositionDiagnostic[];
+}

package/lib/types/src/core/definitions.d.ts

@@ -0,0 +1,16 @@
+import type { MemoryPackageProvenance, MemoryPluginDescriptor, MemorySourceDefinition, MemorySourceManifest, MemoryStrategyDefinition, MemoryStrategyExtensionDefinition } from './contracts/index.ts';
+export declare function requiredText(value: unknown, label: string, maximum?: number): string;
+export declare function id(value: unknown, label: string): string;
+export declare function positiveInteger(value: unknown, label: string, maximum?: number): number;
+/** Canonical JSON representation shared by validation, digest, and replay. */
+export declare function canonicalMemoryJson(value: unknown, label?: string, ancestors?: Set<object>, depth?: number): string;
+export declare function deepFreeze<T>(value: T): T;
+export declare function jsonClone<T>(value: T, label: string): T;
+export declare function uniqueIds(values: readonly string[], label: string): string[];
+export declare function validateProvenance(value: MemoryPackageProvenance, expectedPackage: string): MemoryPackageProvenance;
+export declare function validateCapabilities(values: readonly string[], label: string): MemorySourceManifest['capabilities'];
+/** Validate a plugin node independently of whether its Fiber is active. */
+export declare function defineMemoryPlugin(value: Omit<MemoryPluginDescriptor, 'apiVersion'> | MemoryPluginDescriptor): MemoryPluginDescriptor;
+export declare function defineMemorySource<T extends MemorySourceDefinition>(definition: T): T;
+export declare function defineMemoryStrategy<T extends MemoryStrategyDefinition>(definition: T): T;
+export declare function defineMemoryStrategyExtension<T extends MemoryStrategyExtensionDefinition>(definition: T): T;

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

@@ -0,0 +1,6 @@
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "dsh-mnemon-core";
+export declare const provide: string[];
+export declare const inject: string[];
+/** No built-in Source, Provider, filesystem, settings, tools, or Web dependency. */
+export declare function apply(context: Context): void;

package/lib/types/src/{config-values.d.ts → host/config-values.d.ts}

@@ -1,15 +1,15 @@
+export declare const DEFAULT_IDLE_REVIEW_MS = 30000;
+export declare const DEFAULT_RUNTIME_MEMORY_LIMIT_BYTES: number;
+export declare const DEFAULT_RUNTIME_USER_LIMIT_BYTES: number;
+export declare const MAX_RUNTIME_MEMORY_LIMIT_BYTES: number;
+export declare const DEFAULT_RUNTIME_MAINTENANCE_MAX_TOKENS = 8192;
+export declare const MAX_RUNTIME_MAINTENANCE_MAX_TOKENS = 1000000;
+export { DEFAULT_EMBEDDING_ENDPOINT, DEFAULT_EMBEDDING_MODEL, DEFAULT_EMBEDDING_PROTOCOL, MNEMON_EMBEDDING_PROTOCOLS } from "./protocol.ts";
 export declare const DEFAULT_TIMEOUT_MS = 10000;
 export declare const DEFAULT_RECALL_LIMIT = 10;
-export declare const DEFAULT_IDLE_REVIEW_MS = 30000;
 export declare const DEFAULT_RECALL_QUALITY_POLICY = "strict-v1";
 export declare const DEFAULT_RECALL_LOW_SCORE_THRESHOLD = 0.25;
 export declare const DEFAULT_RECALL_HIGH_SCORE_THRESHOLD = 0.6;
 export declare const DEFAULT_RECALL_CANDIDATE_MULTIPLIER = 3;
 export declare const DEFAULT_RECALL_MAX_MEDIUM_RESULTS = 4;
 export declare const DEFAULT_RECALL_MAX_UNKNOWN_RESULTS = 2;
-export declare const DEFAULT_RUNTIME_MEMORY_LIMIT_BYTES: number;
-export declare const DEFAULT_RUNTIME_USER_LIMIT_BYTES: number;
-export declare const DEFAULT_RUNTIME_MAINTENANCE_MAX_TOKENS = 8192;
-export declare const MAX_RUNTIME_MEMORY_LIMIT_BYTES: number;
-export declare const MAX_RUNTIME_MAINTENANCE_MAX_TOKENS = 1000000;
-export { DEFAULT_EMBEDDING_ENDPOINT, DEFAULT_EMBEDDING_MODEL, DEFAULT_EMBEDDING_PROTOCOL, MNEMON_EMBEDDING_PROTOCOLS } from './shared/contracts.ts';

package/lib/types/src/{config.d.ts → host/config.d.ts}

@@ -1,5 +1,5 @@
 import z from 'schemastery';
-import type { Config as SharedConfig, CustomPackConfig as SharedCustomPackConfig, InteractionConfig as SharedInteractionConfig, ResolvedConfig as SharedResolvedConfig, ResolvedInteractionConfig as SharedResolvedInteractionConfig } from './shared/contracts.ts';
+import type { Config as SharedConfig, CustomPackConfig as SharedCustomPackConfig, InteractionConfig as SharedInteractionConfig, MemoryPersistenceStrategy, RecallQualityConfig, ResolvedConfig as SharedResolvedConfig, ResolvedInteractionConfig as SharedResolvedInteractionConfig } from "./protocol.ts";
 export { DEFAULT_IDLE_REVIEW_MS, DEFAULT_EMBEDDING_ENDPOINT, DEFAULT_EMBEDDING_MODEL, DEFAULT_EMBEDDING_PROTOCOL, DEFAULT_RECALL_CANDIDATE_MULTIPLIER, DEFAULT_RECALL_HIGH_SCORE_THRESHOLD, DEFAULT_RECALL_LIMIT, DEFAULT_RECALL_LOW_SCORE_THRESHOLD, DEFAULT_RECALL_MAX_MEDIUM_RESULTS, DEFAULT_RECALL_MAX_UNKNOWN_RESULTS, DEFAULT_RECALL_QUALITY_POLICY, DEFAULT_RUNTIME_MAINTENANCE_MAX_TOKENS, DEFAULT_RUNTIME_MEMORY_LIMIT_BYTES, DEFAULT_RUNTIME_USER_LIMIT_BYTES, DEFAULT_TIMEOUT_MS, MAX_RUNTIME_MAINTENANCE_MAX_TOKENS, MAX_RUNTIME_MEMORY_LIMIT_BYTES, } from './config-values.ts';
 export type Config = SharedConfig;
 export type CustomPackConfig = SharedCustomPackConfig;
@@ -9,4 +9,7 @@ export type ResolvedInteractionConfig = SharedResolvedInteractionConfig;
 export declare const InteractionConfig: z<InteractionConfig>;
 export declare const Config: z<Config>;
 export declare function resolveInteractionConfig(config?: InteractionConfig): ResolvedInteractionConfig;
+export declare function resolvePersistenceStrategy(value: MemoryPersistenceStrategy | undefined): ResolvedConfig['persistenceStrategy'];
+export declare function resolveEmbedding(value: Config['embedding']): ResolvedConfig['embedding'];
+export declare function resolveRecallQuality(value: RecallQualityConfig | undefined): ResolvedConfig['recallQuality'];
 export declare function resolveConfig(config?: Config): ResolvedConfig;

package/lib/types/src/{shared → host}/display-mode.d.ts

@@ -1,3 +1,3 @@
-import type { MnemonDisplayMode } from './contracts.ts';
+import type { MnemonDisplayMode } from './protocol.ts';
 /** Keep the historical misspelling at input boundaries, never in UI or runtime state. */
 export declare function normalizeDisplayMode(value: unknown): MnemonDisplayMode;

package/lib/types/src/host/plugin.d.ts

@@ -0,0 +1,8 @@
+import { Config, type Config as MnemonConfig } from './config.ts';
+export declare const name = "dsh-mnemon";
+export declare const provide: string[];
+export declare const inject: string[];
+export { Config };
+export type { MnemonConfig };
+/** DSH owns assembly; this Host only wires scope, phases and user preferences. */
+export declare function apply(rawContext: unknown, config?: MnemonConfig): void;