dsh-mnemon-source-runtime 0.5.14 → 0.5.15

package/README.md

@@ -21,6 +21,12 @@ Disabling participation does not delete stored entries. Source data remains sepa
 
 Model projections annotate each entry with its recorded importance and elapsed whole-day ages, for example `[importance=critical; created=14d; updated=2d]`, followed by the exact content. Future timestamps show `future`; unparseable ones show `unknown`. Ages are captured once per projection and remain fixed for that turn. Annotations count toward the Strategy's projection budget, but do not change stored JSON/Markdown, content matching or storage capacity. For replacement/removal, use only the entry content. Current instructions retain priority.
 
+## Storage files
+
+The `./contracts` entry names this Source's files under a storage root (`runtime/memories.json`, `USER.md`, `MEMORY.md`, the `.memories.lock` lock and the `archived/` local archive) and exports the rules a copy of them follows: `runtimeProjection` and `runtimeBytes` write and count USER.md and MEMORY.md exactly as the controller does, and `summarizeRuntimeMemories` counts a stored file for an inventory. They are pure and browser-safe. The `dsh-mnemon` Starter's backup, sync and storage inventory use them instead of keeping copies.
+
+The same entry exports the size limits the configuration and the controller apply: `RUNTIME_MEMORY_LIMITS`, the default limit of USER.md and of MEMORY.md, and `RUNTIME_MEMORY_LIMIT_MAX_BYTES`, the largest limit either may be given. The Starter's settings take their defaults and bounds from them.
+
 ## Source-owned UI and tests
 
 The optional `./client` entry is an ordinary DSH Client plugin. This package owns its pages and `presentation/` resources and uses `dsh-mnemon/client` for the shared frame and scoped management client. It never receives a Host Context, credentials or another Source's controller.

package/lib/contracts-DycwaUv_.js

@@ -0,0 +1,81 @@
+//#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 largest limit, in UTF-8 bytes, either target's file may be given. */
+const RUNTIME_MEMORY_LIMIT_MAX_BYTES = MAX_RUNTIME_MEMORY_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;
+}
+/** The Runtime Source's directory under a storage root. */
+const RUNTIME_DIRECTORY = "runtime";
+/** The entries themselves, the source of truth the projections are written from. */
+const RUNTIME_MEMORIES_FILE = "memories.json";
+/** Each target's projection: its entries' plain content, the file a person reads. */
+const RUNTIME_PROJECTION_FILES = {
+	user: "USER.md",
+	memory: "MEMORY.md"
+};
+/** Created exclusively while the files above are read or written; whoever copies them takes it too. */
+const RUNTIME_LOCK_FILE = ".memories.lock";
+/** A lock file older than this was left by a process that stopped, and may be taken over. */
+const RUNTIME_LOCK_STALE_MS = 3e4;
+/** The local archive of entries that left MEMORY.md while no Memory Space could take them (#336). */
+const RUNTIME_ARCHIVE_DIRECTORY = "archived";
+/** The longest content one entry may hold, in UTF-8 bytes. */
+const RUNTIME_ENTRY_MAX_BYTES = 8192;
+let utf8;
+function joinedContent(entries, target) {
+	return entries.filter((entry) => entry.target === target).map((entry) => entry.content).join(RUNTIME_ENTRY_DELIMITER);
+}
+/** The UTF-8 bytes one target's entries take against its limit: their contents joined by the delimiter. */
+function runtimeBytes(entries, target) {
+	utf8 ??= new TextEncoder();
+	return utf8.encode(joinedContent(entries, target)).byteLength;
+}
+/** One target's projection file, USER.md or MEMORY.md, exactly as the Runtime Source writes it. */
+function runtimeProjection(entries, target) {
+	const content = joinedContent(entries, target);
+	return content === "" ? "" : `${content}\n`;
+}
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Count the entries of a parsed memories.json for a read-only inventory. It never throws: a file
+* without an entry list is not `valid`, and a malformed entry is counted or skipped, never refused.
+*/
+function summarizeRuntimeMemories(value) {
+	const entries = isObject(value) && Array.isArray(value.entries) ? value.entries.filter(isObject) : [];
+	return {
+		valid: isObject(value) && Array.isArray(value.entries),
+		entries: entries.length,
+		user: entries.filter((entry) => entry.target === "user").length,
+		memory: entries.filter((entry) => entry.target === "memory").length
+	};
+}
+//#endregion
+export { summarizeRuntimeMemories as _, RUNTIME_ENTRY_DELIMITER as a, MAX_RUNTIME_MEMORY_LIMIT_BYTES as b, RUNTIME_LOCK_STALE_MS as c, RUNTIME_MEMORY_LIMIT_MAX_BYTES as d, RUNTIME_MEMORY_VERSION as f, runtimeProjection as g, runtimeBytes as h, RUNTIME_DIRECTORY as i, RUNTIME_MEMORIES_FILE as l, parseRuntimeBranches as m, RUNTIME_BRANCH_NAME_MAX as n, RUNTIME_ENTRY_MAX_BYTES as o, RUNTIME_PROJECTION_FILES as p, RUNTIME_BRANCH_NAME_PATTERN as r, RUNTIME_LOCK_FILE as s, RUNTIME_ARCHIVE_DIRECTORY as t, RUNTIME_MEMORY_LIMITS as u, DEFAULT_RUNTIME_MEMORY_LIMIT_BYTES as v, DEFAULT_RUNTIME_USER_LIMIT_BYTES as y };

package/lib/contracts.d.ts

@@ -97,6 +97,8 @@ interface RuntimeMemoryLimits {
   readonly user: number;
 }
 declare const RUNTIME_MEMORY_LIMITS: RuntimeMemoryLimits;
+/** The largest limit, in UTF-8 bytes, either target's file may be given. */
+declare const RUNTIME_MEMORY_LIMIT_MAX_BYTES: number;
 /** 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. */
@@ -107,5 +109,41 @@ declare const RUNTIME_BRANCH_NAME_PATTERN: RegExp;
  * of breaking the projection that reads it.
  */
 declare function parseRuntimeBranches(value: unknown): string[] | undefined;
+/** The Runtime Source's directory under a storage root. */
+declare const RUNTIME_DIRECTORY = "runtime";
+/** The entries themselves, the source of truth the projections are written from. */
+declare const RUNTIME_MEMORIES_FILE = "memories.json";
+/** Each target's projection: its entries' plain content, the file a person reads. */
+declare const RUNTIME_PROJECTION_FILES: {
+  readonly user: "USER.md";
+  readonly memory: "MEMORY.md";
+};
+/** Created exclusively while the files above are read or written; whoever copies them takes it too. */
+declare const RUNTIME_LOCK_FILE = ".memories.lock";
+/** A lock file older than this was left by a process that stopped, and may be taken over. */
+declare const RUNTIME_LOCK_STALE_MS = 30000;
+/** The local archive of entries that left MEMORY.md while no Memory Space could take them (#336). */
+declare const RUNTIME_ARCHIVE_DIRECTORY = "archived";
+/** The longest content one entry may hold, in UTF-8 bytes. */
+declare const RUNTIME_ENTRY_MAX_BYTES: number;
+type RuntimeEntryText = Pick<RuntimeMemoryEntry, 'target' | 'content'>;
+/** The UTF-8 bytes one target's entries take against its limit: their contents joined by the delimiter. */
+declare function runtimeBytes(entries: ReadonlyArray<RuntimeEntryText>, target: RuntimeMemoryTarget): number;
+/** One target's projection file, USER.md or MEMORY.md, exactly as the Runtime Source writes it. */
+declare function runtimeProjection(entries: ReadonlyArray<RuntimeEntryText>, target: RuntimeMemoryTarget): string;
+/** What a stored memories.json holds, counted without judging each entry. */
+interface RuntimeMemoriesSummary {
+  /** Whether the file has an entry list at all. Without one, every count is 0. */
+  valid: boolean;
+  /** Every entry that is an object, whatever its target. */
+  entries: number;
+  user: number;
+  memory: number;
+}
+/**
+ * Count the entries of a parsed memories.json for a read-only inventory. It never throws: a file
+ * without an entry list is not `valid`, and a malformed entry is counted or skipped, never refused.
+ */
+declare function summarizeRuntimeMemories(value: unknown): RuntimeMemoriesSummary;
 //#endregion
-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 };
+export { RUNTIME_ARCHIVE_DIRECTORY, RUNTIME_BRANCH_NAME_MAX, RUNTIME_BRANCH_NAME_PATTERN, RUNTIME_DIRECTORY, RUNTIME_ENTRY_DELIMITER, RUNTIME_ENTRY_MAX_BYTES, RUNTIME_LOCK_FILE, RUNTIME_LOCK_STALE_MS, RUNTIME_MEMORIES_FILE, RUNTIME_MEMORY_LIMITS, RUNTIME_MEMORY_LIMIT_MAX_BYTES, RUNTIME_MEMORY_VERSION, RUNTIME_PROJECTION_FILES, RuntimeMemoriesSummary, RuntimeMemoryAction, RuntimeMemoryCompactedEntry, RuntimeMemoryEntry, RuntimeMemoryEntryOrigin, RuntimeMemoryImportance, RuntimeMemoryLimits, RuntimeMemoryMaintenancePlan, RuntimeMemoryMutation, RuntimeMemoryMutationResult, RuntimeMemorySnapshot, RuntimeMemoryTarget, RuntimeMemoryTargetView, RuntimeMemoryUsage, parseRuntimeBranches, runtimeBytes, runtimeProjection, summarizeRuntimeMemories };

package/lib/contracts.js

@@ -1,2 +1,2 @@
-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 };
+import { _ as summarizeRuntimeMemories, a as RUNTIME_ENTRY_DELIMITER, c as RUNTIME_LOCK_STALE_MS, d as RUNTIME_MEMORY_LIMIT_MAX_BYTES, f as RUNTIME_MEMORY_VERSION, g as runtimeProjection, h as runtimeBytes, i as RUNTIME_DIRECTORY, l as RUNTIME_MEMORIES_FILE, m as parseRuntimeBranches, n as RUNTIME_BRANCH_NAME_MAX, o as RUNTIME_ENTRY_MAX_BYTES, p as RUNTIME_PROJECTION_FILES, r as RUNTIME_BRANCH_NAME_PATTERN, s as RUNTIME_LOCK_FILE, t as RUNTIME_ARCHIVE_DIRECTORY, u as RUNTIME_MEMORY_LIMITS } from "./contracts-DycwaUv_.js";
+export { RUNTIME_ARCHIVE_DIRECTORY, RUNTIME_BRANCH_NAME_MAX, RUNTIME_BRANCH_NAME_PATTERN, RUNTIME_DIRECTORY, RUNTIME_ENTRY_DELIMITER, RUNTIME_ENTRY_MAX_BYTES, RUNTIME_LOCK_FILE, RUNTIME_LOCK_STALE_MS, RUNTIME_MEMORIES_FILE, RUNTIME_MEMORY_LIMITS, RUNTIME_MEMORY_LIMIT_MAX_BYTES, RUNTIME_MEMORY_VERSION, RUNTIME_PROJECTION_FILES, parseRuntimeBranches, runtimeBytes, runtimeProjection, summarizeRuntimeMemories };

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-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 { RUNTIME_ARCHIVE_DIRECTORY, RUNTIME_BRANCH_NAME_MAX, RUNTIME_BRANCH_NAME_PATTERN, RUNTIME_DIRECTORY, RUNTIME_ENTRY_DELIMITER, RUNTIME_ENTRY_MAX_BYTES, RUNTIME_LOCK_FILE, RUNTIME_LOCK_STALE_MS, RUNTIME_MEMORIES_FILE, RUNTIME_MEMORY_LIMITS, RUNTIME_MEMORY_LIMIT_MAX_BYTES, RUNTIME_MEMORY_VERSION, RUNTIME_PROJECTION_FILES, RuntimeMemoriesSummary, RuntimeMemoryAction, RuntimeMemoryCompactedEntry, RuntimeMemoryEntry, RuntimeMemoryEntryOrigin, RuntimeMemoryImportance, RuntimeMemoryLimits, RuntimeMemoryMaintenancePlan, RuntimeMemoryMutation, RuntimeMemoryMutationResult, RuntimeMemorySnapshot, RuntimeMemoryTarget, RuntimeMemoryTargetView, RuntimeMemoryUsage, parseRuntimeBranches, runtimeBytes, runtimeProjection, summarizeRuntimeMemories } 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_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 };
+export { Config, type RUNTIME_ARCHIVE_DIRECTORY, type RUNTIME_BRANCH_NAME_MAX, type RUNTIME_BRANCH_NAME_PATTERN, type RUNTIME_DIRECTORY, type RUNTIME_ENTRY_DELIMITER, type RUNTIME_ENTRY_MAX_BYTES, type RUNTIME_LOCK_FILE, type RUNTIME_LOCK_STALE_MS, type RUNTIME_MEMORIES_FILE, type RUNTIME_MEMORY_LIMITS, type RUNTIME_MEMORY_LIMIT_MAX_BYTES, RUNTIME_MEMORY_SOURCE, type RUNTIME_MEMORY_VERSION, type RUNTIME_PROJECTION_FILES, type RuntimeMemoriesSummary, 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, type runtimeBytes, type runtimeProjection, type summarizeRuntimeMemories };

package/lib/index.js

@@ -1,4 +1,4 @@
-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 { a as RUNTIME_ENTRY_DELIMITER, b as MAX_RUNTIME_MEMORY_LIMIT_BYTES, g as runtimeProjection, h as runtimeBytes, i as RUNTIME_DIRECTORY, l as RUNTIME_MEMORIES_FILE, m as parseRuntimeBranches, o as RUNTIME_ENTRY_MAX_BYTES, p as RUNTIME_PROJECTION_FILES, r as RUNTIME_BRANCH_NAME_PATTERN, s as RUNTIME_LOCK_FILE, t as RUNTIME_ARCHIVE_DIRECTORY, u as RUNTIME_MEMORY_LIMITS } from "./contracts-DycwaUv_.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";
@@ -75,9 +75,7 @@ function resolveGitBranch(cwd) {
 //#endregion
 //#region src/controller.ts
 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);
@@ -147,7 +145,7 @@ function normalizeContent(value, field) {
 	if (content === "") throw new Error(`${field} is required`);
 	if (content.includes("§")) throw new Error(`${field} must not contain the reserved § entry delimiter`);
 	const bytes = Buffer.byteLength(content, "utf8");
-	if (bytes > MAX_ENTRY_BYTES) throw new Error(`${field} is too large (${bytes} bytes; max ${MAX_ENTRY_BYTES})`);
+	if (bytes > 8192) throw new Error(`${field} is too large (${bytes} bytes; max ${RUNTIME_ENTRY_MAX_BYTES})`);
 	return content;
 }
 function parseOrigin(value) {
@@ -177,14 +175,6 @@ function parseEntry(value) {
 		...origin === void 0 ? {} : { origin }
 	};
 }
-function byteCount(entries, target) {
-	const content = entries.filter((entry) => entry.target === target).map((entry) => entry.content).join(RUNTIME_ENTRY_DELIMITER);
-	return Buffer.byteLength(content, "utf8");
-}
-function markdown(entries, target) {
-	const content = entries.filter((entry) => entry.target === target).map((entry) => entry.content).join(RUNTIME_ENTRY_DELIMITER);
-	return content === "" ? "" : `${content}\n`;
-}
 function age(timestamp, projectedAt) {
 	const time = Date.parse(timestamp);
 	if (!Number.isFinite(time)) return "unknown";
@@ -365,14 +355,14 @@ var RuntimeMemoryController = class RuntimeMemoryController {
 			memory: limits.memory,
 			user: limits.user
 		};
-		this.directory = join(runner.effectiveDataDir(), "runtime");
-		this.sourcePath = join(this.directory, "memories.json");
-		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.directory = join(runner.effectiveDataDir(), RUNTIME_DIRECTORY);
+		this.sourcePath = join(this.directory, RUNTIME_MEMORIES_FILE);
+		this.memoryPath = join(this.directory, RUNTIME_PROJECTION_FILES.memory);
+		this.localUserPath = join(this.directory, RUNTIME_PROJECTION_FILES.user);
+		this.lockPath = join(this.directory, RUNTIME_LOCK_FILE);
+		this.archivePath = join(this.directory, RUNTIME_ARCHIVE_DIRECTORY, "MEMORY.md");
+		this.archiveSourcePath = join(this.directory, RUNTIME_ARCHIVE_DIRECTORY, "memories.jsonl");
+		const userDirectory = userRunner === void 0 ? this.directory : join(userRunner.effectiveDataDir(), RUNTIME_DIRECTORY);
 		this.userController = userDirectory === this.directory || userRunner === void 0 ? void 0 : new RuntimeMemoryController(userRunner, now, this.limits);
 		this.userPath = this.userController?.userPath ?? this.localUserPath;
 		this.userSourcePath = this.userController?.sourcePath ?? this.sourcePath;
@@ -487,8 +477,8 @@ ${memory || "(empty)"}
 		const operation = this.queue.then(() => this.withLock(() => {
 			const file = this.readSource();
 			const prepared = prepareMutation(file.entries, request, this.now().toISOString());
-			const used = byteCount(file.entries, request.target);
-			const projected = byteCount(prepared.projectedEntries, request.target);
+			const used = runtimeBytes(file.entries, request.target);
+			const projected = runtimeBytes(prepared.projectedEntries, request.target);
 			const limit = this.limits[request.target];
 			return {
 				revision: revision(file),
@@ -532,9 +522,9 @@ ${memory || "(empty)"}
 			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 used = runtimeBytes(entries, request.target);
 			const limit = this.limits[request.target];
-			if (used > limit) throw new RuntimeMemoryCapacityError(request.target, byteCount(file.entries, request.target), used, limit);
+			if (used > limit) throw new RuntimeMemoryCapacityError(request.target, runtimeBytes(file.entries, request.target), used, limit);
 			const next = {
 				version: 1,
 				entries
@@ -556,7 +546,7 @@ ${memory || "(empty)"}
 	}
 	/** 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");
+		const directory = join(this.directory, RUNTIME_ARCHIVE_DIRECTORY);
 		mkdirSync(directory, {
 			recursive: true,
 			mode: 448
@@ -594,9 +584,9 @@ ${memory || "(empty)"}
 		const file = this.readSource();
 		const prepared = prepareMutation(file.entries, request, this.now().toISOString());
 		if (!prepared.changed) return this.result(request.target, prepared.projectedEntries, prepared.fields);
-		const used = byteCount(prepared.projectedEntries, request.target);
+		const used = runtimeBytes(prepared.projectedEntries, request.target);
 		const limit = this.limits[request.target];
-		if (used > limit) throw new RuntimeMemoryCapacityError(request.target, byteCount(file.entries, request.target), used, limit);
+		if (used > limit) throw new RuntimeMemoryCapacityError(request.target, runtimeBytes(file.entries, request.target), used, limit);
 		this.persist({
 			version: 1,
 			entries: prepared.projectedEntries
@@ -610,7 +600,7 @@ ${memory || "(empty)"}
 			target,
 			entryCount: entries.filter((entry) => entry.target === target).length,
 			usage: {
-				used: byteCount(entries, target),
+				used: runtimeBytes(entries, target),
 				limit: this.limits[target]
 			},
 			...fields.added === void 0 ? {} : { added: fields.added },
@@ -622,7 +612,7 @@ ${memory || "(empty)"}
 		return {
 			target,
 			entryCount: entries.filter((entry) => entry.target === target).length,
-			used: byteCount(entries, target),
+			used: runtimeBytes(entries, target),
 			limit: this.limits[target],
 			markdownPath: target === "memory" ? this.memoryPath : this.userPath
 		};
@@ -667,8 +657,8 @@ ${memory || "(empty)"}
 		});
 		const nonce = `${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}`;
 		const writes = [
-			[this.localUserPath, markdown(file.entries, "user")],
-			[this.memoryPath, markdown(file.entries, "memory")],
+			[this.localUserPath, runtimeProjection(file.entries, "user")],
+			[this.memoryPath, runtimeProjection(file.entries, "memory")],
 			[this.sourcePath, `${JSON.stringify(file, null, 2)}\n`]
 		];
 		const temporaries = writes.map(([path]) => join(this.directory, `.${basename(path)}.${nonce}.tmp`));
@@ -684,7 +674,7 @@ ${memory || "(empty)"}
 	}
 	repairProjections(file) {
 		for (const [path, target] of [[this.localUserPath, "user"], [this.memoryPath, "memory"]]) {
-			const expected = markdown(file.entries, target);
+			const expected = runtimeProjection(file.entries, target);
 			let current;
 			try {
 				current = readFileSync(path, "utf8");
@@ -712,7 +702,7 @@ ${memory || "(empty)"}
 		} catch (error) {
 			if ((isRecord(error) && typeof error.code === "string" ? error.code : void 0) !== "EEXIST") throw error;
 			try {
-				if (Date.now() - statSync(this.lockPath).mtimeMs > LOCK_STALE_MS) {
+				if (Date.now() - statSync(this.lockPath).mtimeMs > 3e4) {
 					rmSync(this.lockPath, { force: true });
 					continue;
 				}

package/lib/types/contracts.d.ts

@@ -96,6 +96,8 @@ export interface RuntimeMemoryLimits {
     readonly user: number;
 }
 export declare const RUNTIME_MEMORY_LIMITS: RuntimeMemoryLimits;
+/** The largest limit, in UTF-8 bytes, either target's file may be given. */
+export declare const RUNTIME_MEMORY_LIMIT_MAX_BYTES: number;
 /** 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. */
@@ -106,3 +108,40 @@ export declare const RUNTIME_BRANCH_NAME_PATTERN: RegExp;
  * of breaking the projection that reads it.
  */
 export declare function parseRuntimeBranches(value: unknown): string[] | undefined;
+/** The Runtime Source's directory under a storage root. */
+export declare const RUNTIME_DIRECTORY = "runtime";
+/** The entries themselves, the source of truth the projections are written from. */
+export declare const RUNTIME_MEMORIES_FILE = "memories.json";
+/** Each target's projection: its entries' plain content, the file a person reads. */
+export declare const RUNTIME_PROJECTION_FILES: {
+    readonly user: "USER.md";
+    readonly memory: "MEMORY.md";
+};
+/** Created exclusively while the files above are read or written; whoever copies them takes it too. */
+export declare const RUNTIME_LOCK_FILE = ".memories.lock";
+/** A lock file older than this was left by a process that stopped, and may be taken over. */
+export declare const RUNTIME_LOCK_STALE_MS = 30000;
+/** The local archive of entries that left MEMORY.md while no Memory Space could take them (#336). */
+export declare const RUNTIME_ARCHIVE_DIRECTORY = "archived";
+/** The longest content one entry may hold, in UTF-8 bytes. */
+export declare const RUNTIME_ENTRY_MAX_BYTES: number;
+type RuntimeEntryText = Pick<RuntimeMemoryEntry, 'target' | 'content'>;
+/** The UTF-8 bytes one target's entries take against its limit: their contents joined by the delimiter. */
+export declare function runtimeBytes(entries: ReadonlyArray<RuntimeEntryText>, target: RuntimeMemoryTarget): number;
+/** One target's projection file, USER.md or MEMORY.md, exactly as the Runtime Source writes it. */
+export declare function runtimeProjection(entries: ReadonlyArray<RuntimeEntryText>, target: RuntimeMemoryTarget): string;
+/** What a stored memories.json holds, counted without judging each entry. */
+export interface RuntimeMemoriesSummary {
+    /** Whether the file has an entry list at all. Without one, every count is 0. */
+    valid: boolean;
+    /** Every entry that is an object, whatever its target. */
+    entries: number;
+    user: number;
+    memory: number;
+}
+/**
+ * Count the entries of a parsed memories.json for a read-only inventory. It never throws: a file
+ * without an entry list is not `valid`, and a malformed entry is counted or skipped, never refused.
+ */
+export declare function summarizeRuntimeMemories(value: unknown): RuntimeMemoriesSummary;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mnemon-source-runtime",
-  "version": "0.5.14",
+  "version": "0.5.15",
   "description": "Self-contained runtime Source for Composable View Memory.",
   "license": "MIT",
   "type": "module",
@@ -55,12 +55,12 @@
     "react": "^18.2.0"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-client-ui-primitives": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.2.1-rc.2",
     "@testing-library/react": "^16.3.0",
     "@types/node": "^22.0.0",
     "@types/react": "^18.3.0",
     "@types/react-dom": "^18.3.0",
-    "dsh-mnemon": "^0.5.26",
+    "dsh-mnemon": "^0.5.32",
     "jsdom": "^26.0.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
@@ -84,9 +84,9 @@
     "micromark-util-sanitize-uri": "^2.0.1",
     "micromark-util-symbol": "^2.0.1",
     "shiki": "^4.3.1",
-    "@deepseek-ai/dsh-client-store": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-util-code-language": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-util-workspace-path": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-store": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-util-code-language": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-util-workspace-path": "0.2.1-rc.2",
     "diff": "^9.0.0",
     "immer": "^10.1.1",
     "simple-icons": "16.31.0",

package/lib/contracts-B6vRCw3C.js

@@ -1,32 +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
-};
-/** 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 };