dsh-mnemon-source-runtime 0.5.12 → 0.5.14

package/lib/client.js

@@ -51,6 +51,7 @@ window.__ModuleLoader__.load({
 			"runtime.result.remove": "已从{target}移除 · 当前 {count} 条",
 			"runtime.result.maintenance": "容量整理完成：已先归档到记忆空间 {spaces}，再更新{target} · 当前 {count} 条",
 			"runtime.result.localCompaction": "本地画像整理完成：未写入记忆空间，已更新{target} · 当前 {count} 条",
+			"runtime.result.localArchive": "容量整理完成：没有可写的记忆空间，已先把 {archived} 条移入本地归档，再更新{target} · 当前 {count} 条",
 			"runtime.readOnly": "当前为只读模式；运行时记忆仍会进入上下文，但不能在此修改。",
 			"runtime.footnote": "memories.json 是唯一事实源；两个 Markdown 文件由控制层生成，不应直接编辑。"
 		};
@@ -97,6 +98,7 @@ window.__ModuleLoader__.load({
 			"runtime.result.remove": "Removed from {target} · {count} entries",
 			"runtime.result.maintenance": "Capacity maintenance complete: archived to {spaces}, then updated {target} · {count} entries",
 			"runtime.result.localCompaction": "Local profile compaction complete: no Memory Space write; updated {target} · {count} entries",
+			"runtime.result.localArchive": "Capacity maintenance complete: with no Memory Space to write to, moved {archived} entries to the local archive, then updated {target} · {count} entries",
 			"runtime.readOnly": "Read only here: runtime memory still enters context but cannot be changed on this page.",
 			"runtime.footnote": "memories.json is the only source of truth. The control plane generates both Markdown files; do not edit them directly."
 		};
@@ -251,6 +253,10 @@ window.__ModuleLoader__.load({
 				}) : result.maintenance.kind === "local-compaction" ? t("runtime.result.localCompaction", {
 					target: t(`runtime.target.${request.target}`),
 					count: result.entryCount
+				}) : result.maintenance.kind === "local-archive" ? t("runtime.result.localArchive", {
+					target: t(`runtime.target.${request.target}`),
+					count: result.entryCount,
+					archived: result.archived?.entries ?? 0
 				}) : t("runtime.result.maintenance", {
 					target: t(`runtime.target.${request.target}`),
 					count: result.entryCount,

package/lib/contracts-B6vRCw3C.js

@@ -0,0 +1,32 @@
+//#region src/defaults.ts
+const DEFAULT_RUNTIME_MEMORY_LIMIT_BYTES = 10240;
+const DEFAULT_RUNTIME_USER_LIMIT_BYTES = 4096;
+const MAX_RUNTIME_MEMORY_LIMIT_BYTES = 1048576;
+//#endregion
+//#region src/contracts.ts
+const RUNTIME_MEMORY_VERSION = 1;
+const RUNTIME_ENTRY_DELIMITER = "\n§\n";
+const RUNTIME_MEMORY_LIMITS = {
+	memory: DEFAULT_RUNTIME_MEMORY_LIMIT_BYTES,
+	user: DEFAULT_RUNTIME_USER_LIMIT_BYTES
+};
+/** The longest git branch name a scope may hold. */
+const RUNTIME_BRANCH_NAME_MAX = 128;
+/** The characters a git branch name in a scope may use. */
+const RUNTIME_BRANCH_NAME_PATTERN = /^[A-Za-z0-9._/-]+$/u;
+/**
+* Read a stored branch scope. Absent or malformed data reads as no scope, so an entry that
+* a hand edit or another installation left malformed is projected on every branch instead
+* of breaking the projection that reads it.
+*/
+function parseRuntimeBranches(value) {
+	if (!Array.isArray(value)) return void 0;
+	const branches = [];
+	for (const item of value) {
+		if (typeof item !== "string" || item === "" || item.length > 128 || !RUNTIME_BRANCH_NAME_PATTERN.test(item)) return void 0;
+		branches.push(item);
+	}
+	return branches;
+}
+//#endregion
+export { RUNTIME_MEMORY_VERSION as a, DEFAULT_RUNTIME_USER_LIMIT_BYTES as c, RUNTIME_MEMORY_LIMITS as i, MAX_RUNTIME_MEMORY_LIMIT_BYTES as l, RUNTIME_BRANCH_NAME_PATTERN as n, parseRuntimeBranches as o, RUNTIME_ENTRY_DELIMITER as r, DEFAULT_RUNTIME_MEMORY_LIMIT_BYTES as s, RUNTIME_BRANCH_NAME_MAX as t };

package/lib/contracts.d.ts

@@ -2,6 +2,12 @@
 type RuntimeMemoryTarget = 'memory' | 'user';
 type RuntimeMemoryImportance = 'critical' | 'normal' | 'low';
 type RuntimeMemoryAction = 'add' | 'replace' | 'remove';
+/** Provenance a DSH Host stamps when an entry crosses machines; absent for local writes. */
+interface RuntimeMemoryEntryOrigin {
+  machine: string;
+  label: string;
+  at: string;
+}
 interface RuntimeMemoryEntry {
   content: string;
   created_at: string;
@@ -10,6 +16,8 @@ interface RuntimeMemoryEntry {
   importance: RuntimeMemoryImportance;
   /** Optional git branch names that limit where this entry is projected. Absent means every branch. */
   branches?: string[];
+  /** Which installation wrote this entry, so a merge can tell two machines apart. */
+  origin?: RuntimeMemoryEntryOrigin;
 }
 interface RuntimeMemoryUsage {
   used: number;
@@ -55,8 +63,13 @@ type RuntimeMemoryMutationResult = {
     to: string;
   };
   removed?: string;
+  /** MEMORY.md entries a compaction moved to the local archive, when it ran with `archive: 'local'`. */
+  archived?: {
+    entries: number;
+    path: string;
+  };
   maintenance?: {
-    kind: 'local-compaction' | 'mnemon-archive';
+    kind: 'local-compaction' | 'mnemon-archive' | 'local-archive';
     runId: string;
     provider: string;
     summary: string;
@@ -74,6 +87,8 @@ interface RuntimeMemoryMaintenancePlan {
   projected: number;
   limit: number;
   requiresMaintenance: boolean;
+  /** This Runtime Source moves the entries compaction leaves out to its local archive when asked (#336). */
+  localArchive?: true;
 }
 declare const RUNTIME_MEMORY_VERSION = 1;
 declare const RUNTIME_ENTRY_DELIMITER = "\n§\n";
@@ -82,5 +97,15 @@ interface RuntimeMemoryLimits {
   readonly user: number;
 }
 declare const RUNTIME_MEMORY_LIMITS: RuntimeMemoryLimits;
+/** The longest git branch name a scope may hold. */
+declare const RUNTIME_BRANCH_NAME_MAX = 128;
+/** The characters a git branch name in a scope may use. */
+declare const RUNTIME_BRANCH_NAME_PATTERN: RegExp;
+/**
+ * Read a stored branch scope. Absent or malformed data reads as no scope, so an entry that
+ * a hand edit or another installation left malformed is projected on every branch instead
+ * of breaking the projection that reads it.
+ */
+declare function parseRuntimeBranches(value: unknown): string[] | undefined;
 //#endregion
-export { RUNTIME_ENTRY_DELIMITER, RUNTIME_MEMORY_LIMITS, RUNTIME_MEMORY_VERSION, RuntimeMemoryAction, RuntimeMemoryCompactedEntry, RuntimeMemoryEntry, RuntimeMemoryImportance, RuntimeMemoryLimits, RuntimeMemoryMaintenancePlan, RuntimeMemoryMutation, RuntimeMemoryMutationResult, RuntimeMemorySnapshot, RuntimeMemoryTarget, RuntimeMemoryTargetView, RuntimeMemoryUsage };
+export { RUNTIME_BRANCH_NAME_MAX, RUNTIME_BRANCH_NAME_PATTERN, RUNTIME_ENTRY_DELIMITER, RUNTIME_MEMORY_LIMITS, RUNTIME_MEMORY_VERSION, RuntimeMemoryAction, RuntimeMemoryCompactedEntry, RuntimeMemoryEntry, RuntimeMemoryEntryOrigin, RuntimeMemoryImportance, RuntimeMemoryLimits, RuntimeMemoryMaintenancePlan, RuntimeMemoryMutation, RuntimeMemoryMutationResult, RuntimeMemorySnapshot, RuntimeMemoryTarget, RuntimeMemoryTargetView, RuntimeMemoryUsage, parseRuntimeBranches };

package/lib/contracts.js

@@ -1,2 +1,2 @@
-import { n as RUNTIME_MEMORY_LIMITS, r as RUNTIME_MEMORY_VERSION, t as RUNTIME_ENTRY_DELIMITER } from "./contracts-BqaPCrGD.js";
-export { RUNTIME_ENTRY_DELIMITER, RUNTIME_MEMORY_LIMITS, RUNTIME_MEMORY_VERSION };
+import { a as RUNTIME_MEMORY_VERSION, i as RUNTIME_MEMORY_LIMITS, n as RUNTIME_BRANCH_NAME_PATTERN, o as parseRuntimeBranches, r as RUNTIME_ENTRY_DELIMITER, t as RUNTIME_BRANCH_NAME_MAX } from "./contracts-B6vRCw3C.js";
+export { RUNTIME_BRANCH_NAME_MAX, RUNTIME_BRANCH_NAME_PATTERN, RUNTIME_ENTRY_DELIMITER, RUNTIME_MEMORY_LIMITS, RUNTIME_MEMORY_VERSION, parseRuntimeBranches };

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-import { RUNTIME_ENTRY_DELIMITER, RUNTIME_MEMORY_LIMITS, RUNTIME_MEMORY_VERSION, RuntimeMemoryAction, RuntimeMemoryCompactedEntry, RuntimeMemoryEntry, RuntimeMemoryImportance, RuntimeMemoryLimits, RuntimeMemoryMaintenancePlan, RuntimeMemoryMutation, RuntimeMemoryMutationResult, RuntimeMemorySnapshot, RuntimeMemoryTarget, RuntimeMemoryTargetView, RuntimeMemoryUsage } from "./contracts.js";
+import { RUNTIME_BRANCH_NAME_MAX, RUNTIME_BRANCH_NAME_PATTERN, RUNTIME_ENTRY_DELIMITER, RUNTIME_MEMORY_LIMITS, RUNTIME_MEMORY_VERSION, RuntimeMemoryAction, RuntimeMemoryCompactedEntry, RuntimeMemoryEntry, RuntimeMemoryEntryOrigin, RuntimeMemoryImportance, RuntimeMemoryLimits, RuntimeMemoryMaintenancePlan, RuntimeMemoryMutation, RuntimeMemoryMutationResult, RuntimeMemorySnapshot, RuntimeMemoryTarget, RuntimeMemoryTargetView, RuntimeMemoryUsage, parseRuntimeBranches } from "./contracts.js";
 import z from "@deepseek-ai/schemastery";
 import { MemorySourceDefinition } from "dsh-mnemon/contracts";
 import { Context } from "@deepseek-ai/cordis";
@@ -21,4 +21,4 @@ declare const inject: string[];
 declare const memoryPlugin: import("dsh-mnemon/extension-sdk").MemoryPluginDescriptor;
 declare function apply(ctx: Context, config?: Config): void;
 //#endregion
-export { Config, type RUNTIME_ENTRY_DELIMITER, type RUNTIME_MEMORY_LIMITS, RUNTIME_MEMORY_SOURCE, type RUNTIME_MEMORY_VERSION, type RuntimeMemoryAction, type RuntimeMemoryCompactedEntry, type RuntimeMemoryEntry, type RuntimeMemoryImportance, type RuntimeMemoryLimits, type RuntimeMemoryMaintenancePlan, type RuntimeMemoryMutation, type RuntimeMemoryMutationResult, type RuntimeMemorySnapshot, type RuntimeMemoryTarget, type RuntimeMemoryTargetView, type RuntimeMemoryUsage, apply, createRuntimeMemorySource, inject, memoryPlugin, name };
+export { Config, type RUNTIME_BRANCH_NAME_MAX, type RUNTIME_BRANCH_NAME_PATTERN, type RUNTIME_ENTRY_DELIMITER, type RUNTIME_MEMORY_LIMITS, RUNTIME_MEMORY_SOURCE, type RUNTIME_MEMORY_VERSION, type RuntimeMemoryAction, type RuntimeMemoryCompactedEntry, type RuntimeMemoryEntry, type RuntimeMemoryEntryOrigin, type RuntimeMemoryImportance, type RuntimeMemoryLimits, type RuntimeMemoryMaintenancePlan, type RuntimeMemoryMutation, type RuntimeMemoryMutationResult, type RuntimeMemorySnapshot, type RuntimeMemoryTarget, type RuntimeMemoryTargetView, type RuntimeMemoryUsage, apply, createRuntimeMemorySource, inject, memoryPlugin, name, type parseRuntimeBranches };

package/lib/index.js

@@ -1,11 +1,11 @@
-import { n as RUNTIME_MEMORY_LIMITS, o as MAX_RUNTIME_MEMORY_LIMIT_BYTES, t as RUNTIME_ENTRY_DELIMITER } from "./contracts-BqaPCrGD.js";
+import { i as RUNTIME_MEMORY_LIMITS, l as MAX_RUNTIME_MEMORY_LIMIT_BYTES, n as RUNTIME_BRANCH_NAME_PATTERN, o as parseRuntimeBranches, r as RUNTIME_ENTRY_DELIMITER } from "./contracts-B6vRCw3C.js";
 import { createMemoryMutationReceipt, defineMemoryPlugin, defineMemorySource, installMemory, memoryConfigurationDigest, memoryInputRecord, memoryInputStringArray, memoryInputText, truncateMemoryText } from "dsh-mnemon/extension-sdk";
 import { homedir } from "node:os";
 import { basename, isAbsolute, join } from "node:path";
 import z from "@deepseek-ai/schemastery";
 import { COMPOSABLE_MEMORY_API_VERSION } from "dsh-mnemon/contracts";
 import { execFileSync } from "node:child_process";
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
 import { createHash } from "node:crypto";
 //#region src/config.ts
 const Config = z.object({
@@ -34,6 +34,19 @@ const GIT_BRANCH_TIMEOUT_MS = 2e3;
 * the directory is not a git working tree, HEAD is detached, or the probe
 * fails or times out, so callers fall back to the unfiltered view.
 */
+/**
+* Git takes the repository location from the environment, so a launcher that
+* exports `GIT_DIR` for its own reasons would point this probe at a directory
+* that is not the workspace. The probe runs with those variables removed.
+*/
+function gitEnvironment(environment = process.env) {
+	const sanitized = {};
+	for (const [name, value] of Object.entries(environment)) {
+		if (value === void 0 || name.toUpperCase().startsWith("GIT_")) continue;
+		sanitized[name] = value;
+	}
+	return sanitized;
+}
 function resolveGitBranch(cwd) {
 	const root = cwd?.trim();
 	if (root === void 0 || root === "") return void 0;
@@ -51,7 +64,8 @@ function resolveGitBranch(cwd) {
 				"pipe",
 				"ignore"
 			],
-			windowsHide: true
+			windowsHide: true,
+			env: gitEnvironment()
 		}).trim();
 		return branch === "" ? void 0 : branch;
 	} catch {
@@ -64,6 +78,16 @@ const LOCK_TIMEOUT_MS = 5e3;
 const LOCK_STALE_MS = 3e4;
 const LOCK_RETRY_MS = 20;
 const MAX_ENTRY_BYTES = 8192;
+/** Append to a file that is not a symbolic link; the open fails on one. */
+function appendWithoutLinks(path, text) {
+	const descriptor = openSync(path, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | (constants.O_NOFOLLOW ?? 0), 384);
+	try {
+		const bytes = Buffer.from(text, "utf8");
+		for (let offset = 0; offset < bytes.length;) offset += writeSync(descriptor, bytes, offset, bytes.length - offset);
+	} finally {
+		closeSync(descriptor);
+	}
+}
 var RuntimeMemoryCapacityError = class extends Error {
 	target;
 	used;
@@ -95,7 +119,6 @@ function isTarget(value) {
 function isImportance(value) {
 	return value === "critical" || value === "normal" || value === "low";
 }
-const RUNTIME_BRANCH_NAME_RE = /^[A-Za-z0-9._/-]+$/u;
 /** Validate a model-supplied branch scope. Returns the normalized list; an empty list means "no scope". */
 function normalizeRuntimeBranches(value, field = "branches") {
 	if (!Array.isArray(value)) throw new Error(`${field} must be an array of git branch names`);
@@ -104,7 +127,7 @@ function normalizeRuntimeBranches(value, field = "branches") {
 	for (const item of value) {
 		if (typeof item !== "string") throw new Error(`${field} must contain only git branch names`);
 		const branch = item.trim();
-		if (branch === "" || branch.length > 128 || !RUNTIME_BRANCH_NAME_RE.test(branch) || branch === "-" || branch.startsWith("/") || branch.startsWith("-") || branch.endsWith("/") || branch.endsWith(".") || branch.includes("..") || branch.includes("//") || branch.includes("@{")) throw new Error(`${field} must contain git branch names (letters, numbers, dot, underscore, slash, dash)`);
+		if (branch === "" || branch.length > 128 || !RUNTIME_BRANCH_NAME_PATTERN.test(branch) || branch === "-" || branch.startsWith("/") || branch.startsWith("-") || branch.endsWith("/") || branch.endsWith(".") || branch.includes("..") || branch.includes("//") || branch.includes("@{")) throw new Error(`${field} must contain git branch names (letters, numbers, dot, underscore, slash, dash)`);
 		if (seen.has(branch)) throw new Error(`${field} must not repeat a branch name`);
 		seen.add(branch);
 		branches.push(branch);
@@ -112,17 +135,6 @@ function normalizeRuntimeBranches(value, field = "branches") {
 	if (branches.length > 16) throw new Error(`${field} supports at most 16 branch names`);
 	return branches;
 }
-/** Parse a stored branch scope. Returns undefined for absent or invalid data. */
-function parseRuntimeBranches(value) {
-	if (value === void 0) return void 0;
-	if (!Array.isArray(value)) return void 0;
-	const branches = [];
-	for (const item of value) {
-		if (typeof item !== "string" || item === "" || item.length > 128 || !RUNTIME_BRANCH_NAME_RE.test(item)) return void 0;
-		branches.push(item);
-	}
-	return branches;
-}
 function entryMatchesBranch(entry, branch) {
 	return entry.branches === void 0 || entry.branches.length === 0 || entry.branches.includes(branch);
 }
@@ -138,6 +150,15 @@ function normalizeContent(value, field) {
 	if (bytes > MAX_ENTRY_BYTES) throw new Error(`${field} is too large (${bytes} bytes; max ${MAX_ENTRY_BYTES})`);
 	return content;
 }
+function parseOrigin(value) {
+	if (!isRecord(value)) return void 0;
+	if (typeof value.machine !== "string" || typeof value.label !== "string" || typeof value.at !== "string") return void 0;
+	return {
+		machine: value.machine,
+		label: value.label,
+		at: value.at
+	};
+}
 function parseEntry(value) {
 	if (!isRecord(value) || typeof value.content !== "string" || !isTarget(value.target) || !isImportance(value.importance)) return void 0;
 	if (typeof value.created_at !== "string" || typeof value.updated_at !== "string") return void 0;
@@ -145,13 +166,15 @@ function parseEntry(value) {
 	if (content === "" || content.includes("§")) return void 0;
 	if (value.target === "user" && value.branches !== void 0) return void 0;
 	const branches = parseRuntimeBranches(value.branches);
+	const origin = parseOrigin(value.origin);
 	return {
 		content,
 		created_at: value.created_at,
 		updated_at: value.updated_at,
 		target: value.target,
 		importance: value.importance,
-		...branches === void 0 ? {} : { branches }
+		...branches === void 0 ? {} : { branches },
+		...origin === void 0 ? {} : { origin }
 	};
 }
 function byteCount(entries, target) {
@@ -328,6 +351,9 @@ var RuntimeMemoryController = class RuntimeMemoryController {
 	memoryPath;
 	userPath;
 	lockPath;
+	/** Where MEMORY.md entries go when compaction leaves them out and no Memory Space can take them. */
+	archivePath;
+	archiveSourcePath;
 	limits;
 	queue = Promise.resolve();
 	localUserPath;
@@ -344,6 +370,8 @@ var RuntimeMemoryController = class RuntimeMemoryController {
 		this.memoryPath = join(this.directory, "MEMORY.md");
 		this.localUserPath = join(this.directory, "USER.md");
 		this.lockPath = join(this.directory, ".memories.lock");
+		this.archivePath = join(this.directory, "archived", "MEMORY.md");
+		this.archiveSourcePath = join(this.directory, "archived", "memories.jsonl");
 		const userDirectory = userRunner === void 0 ? this.directory : join(userRunner.effectiveDataDir(), "runtime");
 		this.userController = userDirectory === this.directory || userRunner === void 0 ? void 0 : new RuntimeMemoryController(userRunner, now, this.limits);
 		this.userPath = this.userController?.userPath ?? this.localUserPath;
@@ -475,18 +503,24 @@ ${memory || "(empty)"}
 				used,
 				projected,
 				limit,
-				requiresMaintenance: prepared.changed && projected > limit
+				requiresMaintenance: prepared.changed && projected > limit,
+				localArchive: true
 			};
 		}));
 		this.queue = operation.catch(() => void 0);
 		return operation;
 	}
-	/** Commit semantic compaction and the original mutation together, or leave every local file unchanged. */
-	compactAndMutate(expectedRevision, request, compacted, maxCompactedBytes) {
+	/**
+	* Commit semantic compaction and the original mutation together, or leave every local file unchanged.
+	* With `archive: 'local'`, committed MEMORY.md entries that compaction leaves out are appended to the
+	* local archive first, so a limit with no Memory Space to archive into never loses memory.
+	*/
+	compactAndMutate(expectedRevision, request, compacted, maxCompactedBytes, options = {}) {
 		if (request.target === "user" && this.userController !== void 0) return this.userController.compactAndMutate(expectedRevision, request, compacted, maxCompactedBytes);
 		const operation = this.queue.then(() => this.withLock(() => {
 			const file = this.readSource();
-			if (revision(file) !== expectedRevision) throw new RuntimeMemoryConflictError();
+			const beforeRevision = revision(file);
+			if (beforeRevision !== expectedRevision) throw new RuntimeMemoryConflictError();
 			const now = this.now().toISOString();
 			const prepared = prepareMutation(file.entries, request, now);
 			const compactedByteBudget = maxCompactedBytes ?? this.limits[request.target];
@@ -495,7 +529,8 @@ ${memory || "(empty)"}
 			const replacements = compactionCandidates(compacted, prepared.compactableEntries, request.target, now);
 			if (prepared.pendingEntry !== void 0 && replacements.some((entry) => entry.content === prepared.pendingEntry.content)) throw new Error("compacted runtime memory duplicates the pending mutation");
 			if (prepared.excludedEntry !== void 0 && replacements.some((entry) => entry.content === prepared.excludedEntry.content)) throw new Error("compacted runtime memory reintroduces the replaced or removed entry");
-			const targetEntries = [...packCompactionCandidates(replacements, request.target, compactedByteBudget), ...prepared.pendingEntry === void 0 ? [] : [prepared.pendingEntry]];
+			const fitted = packCompactionCandidates(replacements, request.target, compactedByteBudget);
+			const targetEntries = [...fitted, ...prepared.pendingEntry === void 0 ? [] : [prepared.pendingEntry]];
 			const entries = [...file.entries.filter((entry) => entry.target !== request.target), ...targetEntries];
 			const used = byteCount(entries, request.target);
 			const limit = this.limits[request.target];
@@ -504,12 +539,47 @@ ${memory || "(empty)"}
 				version: 1,
 				entries
 			};
+			const kept = new Set(fitted.map((entry) => entry.content));
+			const archived = options.archive === "local" && request.target === "memory" ? prepared.compactableEntries.filter((entry) => !kept.has(entry.content)) : void 0;
+			if (archived !== void 0 && archived.length > 0) this.archiveLocally(archived, beforeRevision, now);
 			this.persist(next);
-			return this.result(request.target, entries, prepared.fields);
+			return {
+				...this.result(request.target, entries, prepared.fields),
+				...archived === void 0 ? {} : { archived: {
+					entries: archived.length,
+					path: this.archivePath
+				} }
+			};
 		}));
 		this.queue = operation.catch(() => void 0);
 		return operation;
 	}
+	/** Append entries to the local archive: JSON Lines to restore from, and Markdown to read. */
+	archiveLocally(entries, fromRevision, archivedAt) {
+		const directory = join(this.directory, "archived");
+		mkdirSync(directory, {
+			recursive: true,
+			mode: 448
+		});
+		const stat = lstatSync(directory);
+		if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error(`Runtime Memory archive is not a directory: ${directory}`);
+		for (const path of [this.archiveSourcePath, this.archivePath]) {
+			let file;
+			try {
+				file = lstatSync(path);
+			} catch {
+				continue;
+			}
+			if (!file.isFile()) throw new Error(`Runtime Memory archive file is not a regular file: ${path}`);
+		}
+		appendWithoutLinks(this.archiveSourcePath, entries.map((entry) => `${JSON.stringify({
+			archivedAt,
+			fromRevision,
+			...entry
+		})}\n`).join(""));
+		const header = existsSync(this.archivePath) ? "" : "# MEMORY.md archive\n\nEntries that left MEMORY.md at its limit while no Memory Space could take them, oldest first.\n";
+		appendWithoutLinks(this.archivePath, `${header}\n## ${archivedAt}\n\n${entries.map((entry) => entry.content).join(RUNTIME_ENTRY_DELIMITER)}\n`);
+	}
 	initialize() {
 		mkdirSync(this.directory, {
 			recursive: true,
@@ -843,7 +913,8 @@ function createRuntimeMemorySource(config = {}) {
 								...entry.branches === void 0 ? {} : { branches: memoryInputStringArray(entry.branches, "branches", 100) ?? [] }
 							};
 						});
-						result = await controller.compactAndMutate(memoryInputText(input.revision, "revision", 300), runtimeMutation(input.mutation), compacted, typeof input.maxBytes === "number" ? input.maxBytes : void 0);
+						if (input.archive !== void 0 && input.archive !== "local") throw new Error("archive must be \"local\" when given");
+						result = await controller.compactAndMutate(memoryInputText(input.revision, "revision", 300), runtimeMutation(input.mutation), compacted, typeof input.maxBytes === "number" ? input.maxBytes : void 0, input.archive === "local" ? { archive: "local" } : {});
 					} else throw new Error("unsupported Runtime management mutation operation: " + request.operation);
 					return {
 						revision: controller.snapshot().revision,

package/lib/types/contracts.d.ts

@@ -1,6 +1,12 @@
 export type RuntimeMemoryTarget = 'memory' | 'user';
 export type RuntimeMemoryImportance = 'critical' | 'normal' | 'low';
 export type RuntimeMemoryAction = 'add' | 'replace' | 'remove';
+/** Provenance a DSH Host stamps when an entry crosses machines; absent for local writes. */
+export interface RuntimeMemoryEntryOrigin {
+    machine: string;
+    label: string;
+    at: string;
+}
 export interface RuntimeMemoryEntry {
     content: string;
     created_at: string;
@@ -9,6 +15,8 @@ export interface RuntimeMemoryEntry {
     importance: RuntimeMemoryImportance;
     /** Optional git branch names that limit where this entry is projected. Absent means every branch. */
     branches?: string[];
+    /** Which installation wrote this entry, so a merge can tell two machines apart. */
+    origin?: RuntimeMemoryEntryOrigin;
 }
 export interface RuntimeMemoryUsage {
     used: number;
@@ -54,8 +62,13 @@ export type RuntimeMemoryMutationResult = {
         to: string;
     };
     removed?: string;
+    /** MEMORY.md entries a compaction moved to the local archive, when it ran with `archive: 'local'`. */
+    archived?: {
+        entries: number;
+        path: string;
+    };
     maintenance?: {
-        kind: 'local-compaction' | 'mnemon-archive';
+        kind: 'local-compaction' | 'mnemon-archive' | 'local-archive';
         runId: string;
         provider: string;
         summary: string;
@@ -73,6 +86,8 @@ export interface RuntimeMemoryMaintenancePlan {
     projected: number;
     limit: number;
     requiresMaintenance: boolean;
+    /** This Runtime Source moves the entries compaction leaves out to its local archive when asked (#336). */
+    localArchive?: true;
 }
 export declare const RUNTIME_MEMORY_VERSION = 1;
 export declare const RUNTIME_ENTRY_DELIMITER = "\n\u00A7\n";
@@ -81,3 +96,13 @@ export interface RuntimeMemoryLimits {
     readonly user: number;
 }
 export declare const RUNTIME_MEMORY_LIMITS: RuntimeMemoryLimits;
+/** The longest git branch name a scope may hold. */
+export declare const RUNTIME_BRANCH_NAME_MAX = 128;
+/** The characters a git branch name in a scope may use. */
+export declare const RUNTIME_BRANCH_NAME_PATTERN: RegExp;
+/**
+ * Read a stored branch scope. Absent or malformed data reads as no scope, so an entry that
+ * a hand edit or another installation left malformed is projected on every branch instead
+ * of breaking the projection that reads it.
+ */
+export declare function parseRuntimeBranches(value: unknown): string[] | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mnemon-source-runtime",
-  "version": "0.5.12",
+  "version": "0.5.14",
   "description": "Self-contained runtime Source for Composable View Memory.",
   "license": "MIT",
   "type": "module",
@@ -60,7 +60,7 @@
     "@types/node": "^22.0.0",
     "@types/react": "^18.3.0",
     "@types/react-dom": "^18.3.0",
-    "dsh-mnemon": "^0.5.23",
+    "dsh-mnemon": "^0.5.26",
     "jsdom": "^26.0.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",

package/presentation/locales.json

@@ -42,6 +42,7 @@
     "runtime.result.remove": "已从{target}移除 · 当前 {count} 条",
     "runtime.result.maintenance": "容量整理完成：已先归档到记忆空间 {spaces}，再更新{target} · 当前 {count} 条",
     "runtime.result.localCompaction": "本地画像整理完成：未写入记忆空间，已更新{target} · 当前 {count} 条",
+    "runtime.result.localArchive": "容量整理完成：没有可写的记忆空间，已先把 {archived} 条移入本地归档，再更新{target} · 当前 {count} 条",
     "runtime.readOnly": "当前为只读模式；运行时记忆仍会进入上下文，但不能在此修改。",
     "runtime.footnote": "memories.json 是唯一事实源；两个 Markdown 文件由控制层生成，不应直接编辑。"
   },
@@ -88,6 +89,7 @@
     "runtime.result.remove": "Removed from {target} · {count} entries",
     "runtime.result.maintenance": "Capacity maintenance complete: archived to {spaces}, then updated {target} · {count} entries",
     "runtime.result.localCompaction": "Local profile compaction complete: no Memory Space write; updated {target} · {count} entries",
+    "runtime.result.localArchive": "Capacity maintenance complete: with no Memory Space to write to, moved {archived} entries to the local archive, then updated {target} · {count} entries",
     "runtime.readOnly": "Read only here: runtime memory still enters context but cannot be changed on this page.",
     "runtime.footnote": "memories.json is the only source of truth. The control plane generates both Markdown files; do not edit them directly."
   }

package/lib/contracts-BqaPCrGD.js

@@ -1,14 +0,0 @@
-//#region src/defaults.ts
-const DEFAULT_RUNTIME_MEMORY_LIMIT_BYTES = 10240;
-const DEFAULT_RUNTIME_USER_LIMIT_BYTES = 4096;
-const MAX_RUNTIME_MEMORY_LIMIT_BYTES = 1048576;
-//#endregion
-//#region src/contracts.ts
-const RUNTIME_MEMORY_VERSION = 1;
-const RUNTIME_ENTRY_DELIMITER = "\n§\n";
-const RUNTIME_MEMORY_LIMITS = {
-	memory: DEFAULT_RUNTIME_MEMORY_LIMIT_BYTES,
-	user: DEFAULT_RUNTIME_USER_LIMIT_BYTES
-};
-//#endregion
-export { DEFAULT_RUNTIME_USER_LIMIT_BYTES as a, DEFAULT_RUNTIME_MEMORY_LIMIT_BYTES as i, RUNTIME_MEMORY_LIMITS as n, MAX_RUNTIME_MEMORY_LIMIT_BYTES as o, RUNTIME_MEMORY_VERSION as r, RUNTIME_ENTRY_DELIMITER as t };