dsh-mnemon-source-runtime 0.5.13 → 0.5.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -21,6 +21,12 @@ Disabling participation does not delete stored entries. Source data remains sepa
21
21
 
22
22
  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.
23
23
 
24
+ ## Storage files
25
+
26
+ 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.
27
+
28
+ 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.
29
+
24
30
  ## Source-owned UI and tests
25
31
 
26
32
  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.
@@ -0,0 +1,81 @@
1
+ //#region src/defaults.ts
2
+ const DEFAULT_RUNTIME_MEMORY_LIMIT_BYTES = 10240;
3
+ const DEFAULT_RUNTIME_USER_LIMIT_BYTES = 4096;
4
+ const MAX_RUNTIME_MEMORY_LIMIT_BYTES = 1048576;
5
+ //#endregion
6
+ //#region src/contracts.ts
7
+ const RUNTIME_MEMORY_VERSION = 1;
8
+ const RUNTIME_ENTRY_DELIMITER = "\n§\n";
9
+ const RUNTIME_MEMORY_LIMITS = {
10
+ memory: DEFAULT_RUNTIME_MEMORY_LIMIT_BYTES,
11
+ user: DEFAULT_RUNTIME_USER_LIMIT_BYTES
12
+ };
13
+ /** The largest limit, in UTF-8 bytes, either target's file may be given. */
14
+ const RUNTIME_MEMORY_LIMIT_MAX_BYTES = MAX_RUNTIME_MEMORY_LIMIT_BYTES;
15
+ /** The longest git branch name a scope may hold. */
16
+ const RUNTIME_BRANCH_NAME_MAX = 128;
17
+ /** The characters a git branch name in a scope may use. */
18
+ const RUNTIME_BRANCH_NAME_PATTERN = /^[A-Za-z0-9._/-]+$/u;
19
+ /**
20
+ * Read a stored branch scope. Absent or malformed data reads as no scope, so an entry that
21
+ * a hand edit or another installation left malformed is projected on every branch instead
22
+ * of breaking the projection that reads it.
23
+ */
24
+ function parseRuntimeBranches(value) {
25
+ if (!Array.isArray(value)) return void 0;
26
+ const branches = [];
27
+ for (const item of value) {
28
+ if (typeof item !== "string" || item === "" || item.length > 128 || !RUNTIME_BRANCH_NAME_PATTERN.test(item)) return void 0;
29
+ branches.push(item);
30
+ }
31
+ return branches;
32
+ }
33
+ /** The Runtime Source's directory under a storage root. */
34
+ const RUNTIME_DIRECTORY = "runtime";
35
+ /** The entries themselves, the source of truth the projections are written from. */
36
+ const RUNTIME_MEMORIES_FILE = "memories.json";
37
+ /** Each target's projection: its entries' plain content, the file a person reads. */
38
+ const RUNTIME_PROJECTION_FILES = {
39
+ user: "USER.md",
40
+ memory: "MEMORY.md"
41
+ };
42
+ /** Created exclusively while the files above are read or written; whoever copies them takes it too. */
43
+ const RUNTIME_LOCK_FILE = ".memories.lock";
44
+ /** A lock file older than this was left by a process that stopped, and may be taken over. */
45
+ const RUNTIME_LOCK_STALE_MS = 3e4;
46
+ /** The local archive of entries that left MEMORY.md while no Memory Space could take them (#336). */
47
+ const RUNTIME_ARCHIVE_DIRECTORY = "archived";
48
+ /** The longest content one entry may hold, in UTF-8 bytes. */
49
+ const RUNTIME_ENTRY_MAX_BYTES = 8192;
50
+ let utf8;
51
+ function joinedContent(entries, target) {
52
+ return entries.filter((entry) => entry.target === target).map((entry) => entry.content).join(RUNTIME_ENTRY_DELIMITER);
53
+ }
54
+ /** The UTF-8 bytes one target's entries take against its limit: their contents joined by the delimiter. */
55
+ function runtimeBytes(entries, target) {
56
+ utf8 ??= new TextEncoder();
57
+ return utf8.encode(joinedContent(entries, target)).byteLength;
58
+ }
59
+ /** One target's projection file, USER.md or MEMORY.md, exactly as the Runtime Source writes it. */
60
+ function runtimeProjection(entries, target) {
61
+ const content = joinedContent(entries, target);
62
+ return content === "" ? "" : `${content}\n`;
63
+ }
64
+ function isObject(value) {
65
+ return typeof value === "object" && value !== null && !Array.isArray(value);
66
+ }
67
+ /**
68
+ * Count the entries of a parsed memories.json for a read-only inventory. It never throws: a file
69
+ * without an entry list is not `valid`, and a malformed entry is counted or skipped, never refused.
70
+ */
71
+ function summarizeRuntimeMemories(value) {
72
+ const entries = isObject(value) && Array.isArray(value.entries) ? value.entries.filter(isObject) : [];
73
+ return {
74
+ valid: isObject(value) && Array.isArray(value.entries),
75
+ entries: entries.length,
76
+ user: entries.filter((entry) => entry.target === "user").length,
77
+ memory: entries.filter((entry) => entry.target === "memory").length
78
+ };
79
+ }
80
+ //#endregion
81
+ 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 };
@@ -2,6 +2,12 @@
2
2
  type RuntimeMemoryTarget = 'memory' | 'user';
3
3
  type RuntimeMemoryImportance = 'critical' | 'normal' | 'low';
4
4
  type RuntimeMemoryAction = 'add' | 'replace' | 'remove';
5
+ /** Provenance a DSH Host stamps when an entry crosses machines; absent for local writes. */
6
+ interface RuntimeMemoryEntryOrigin {
7
+ machine: string;
8
+ label: string;
9
+ at: string;
10
+ }
5
11
  interface RuntimeMemoryEntry {
6
12
  content: string;
7
13
  created_at: string;
@@ -10,6 +16,8 @@ interface RuntimeMemoryEntry {
10
16
  importance: RuntimeMemoryImportance;
11
17
  /** Optional git branch names that limit where this entry is projected. Absent means every branch. */
12
18
  branches?: string[];
19
+ /** Which installation wrote this entry, so a merge can tell two machines apart. */
20
+ origin?: RuntimeMemoryEntryOrigin;
13
21
  }
14
22
  interface RuntimeMemoryUsage {
15
23
  used: number;
@@ -89,5 +97,53 @@ interface RuntimeMemoryLimits {
89
97
  readonly user: number;
90
98
  }
91
99
  declare const RUNTIME_MEMORY_LIMITS: RuntimeMemoryLimits;
100
+ /** The largest limit, in UTF-8 bytes, either target's file may be given. */
101
+ declare const RUNTIME_MEMORY_LIMIT_MAX_BYTES: number;
102
+ /** The longest git branch name a scope may hold. */
103
+ declare const RUNTIME_BRANCH_NAME_MAX = 128;
104
+ /** The characters a git branch name in a scope may use. */
105
+ declare const RUNTIME_BRANCH_NAME_PATTERN: RegExp;
106
+ /**
107
+ * Read a stored branch scope. Absent or malformed data reads as no scope, so an entry that
108
+ * a hand edit or another installation left malformed is projected on every branch instead
109
+ * of breaking the projection that reads it.
110
+ */
111
+ declare function parseRuntimeBranches(value: unknown): string[] | undefined;
112
+ /** The Runtime Source's directory under a storage root. */
113
+ declare const RUNTIME_DIRECTORY = "runtime";
114
+ /** The entries themselves, the source of truth the projections are written from. */
115
+ declare const RUNTIME_MEMORIES_FILE = "memories.json";
116
+ /** Each target's projection: its entries' plain content, the file a person reads. */
117
+ declare const RUNTIME_PROJECTION_FILES: {
118
+ readonly user: "USER.md";
119
+ readonly memory: "MEMORY.md";
120
+ };
121
+ /** Created exclusively while the files above are read or written; whoever copies them takes it too. */
122
+ declare const RUNTIME_LOCK_FILE = ".memories.lock";
123
+ /** A lock file older than this was left by a process that stopped, and may be taken over. */
124
+ declare const RUNTIME_LOCK_STALE_MS = 30000;
125
+ /** The local archive of entries that left MEMORY.md while no Memory Space could take them (#336). */
126
+ declare const RUNTIME_ARCHIVE_DIRECTORY = "archived";
127
+ /** The longest content one entry may hold, in UTF-8 bytes. */
128
+ declare const RUNTIME_ENTRY_MAX_BYTES: number;
129
+ type RuntimeEntryText = Pick<RuntimeMemoryEntry, 'target' | 'content'>;
130
+ /** The UTF-8 bytes one target's entries take against its limit: their contents joined by the delimiter. */
131
+ declare function runtimeBytes(entries: ReadonlyArray<RuntimeEntryText>, target: RuntimeMemoryTarget): number;
132
+ /** One target's projection file, USER.md or MEMORY.md, exactly as the Runtime Source writes it. */
133
+ declare function runtimeProjection(entries: ReadonlyArray<RuntimeEntryText>, target: RuntimeMemoryTarget): string;
134
+ /** What a stored memories.json holds, counted without judging each entry. */
135
+ interface RuntimeMemoriesSummary {
136
+ /** Whether the file has an entry list at all. Without one, every count is 0. */
137
+ valid: boolean;
138
+ /** Every entry that is an object, whatever its target. */
139
+ entries: number;
140
+ user: number;
141
+ memory: number;
142
+ }
143
+ /**
144
+ * Count the entries of a parsed memories.json for a read-only inventory. It never throws: a file
145
+ * without an entry list is not `valid`, and a malformed entry is counted or skipped, never refused.
146
+ */
147
+ declare function summarizeRuntimeMemories(value: unknown): RuntimeMemoriesSummary;
92
148
  //#endregion
93
- export { RUNTIME_ENTRY_DELIMITER, RUNTIME_MEMORY_LIMITS, RUNTIME_MEMORY_VERSION, RuntimeMemoryAction, RuntimeMemoryCompactedEntry, RuntimeMemoryEntry, RuntimeMemoryImportance, RuntimeMemoryLimits, RuntimeMemoryMaintenancePlan, RuntimeMemoryMutation, RuntimeMemoryMutationResult, RuntimeMemorySnapshot, RuntimeMemoryTarget, RuntimeMemoryTargetView, RuntimeMemoryUsage };
149
+ 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 CHANGED
@@ -1,2 +1,2 @@
1
- import { n as RUNTIME_MEMORY_LIMITS, r as RUNTIME_MEMORY_VERSION, t as RUNTIME_ENTRY_DELIMITER } from "./contracts-BqaPCrGD.js";
2
- export { RUNTIME_ENTRY_DELIMITER, RUNTIME_MEMORY_LIMITS, RUNTIME_MEMORY_VERSION };
1
+ 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";
2
+ 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 CHANGED
@@ -1,4 +1,4 @@
1
- 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";
1
+ 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";
2
2
  import z from "@deepseek-ai/schemastery";
3
3
  import { MemorySourceDefinition } from "dsh-mnemon/contracts";
4
4
  import { Context } from "@deepseek-ai/cordis";
@@ -21,4 +21,4 @@ declare const inject: string[];
21
21
  declare const memoryPlugin: import("dsh-mnemon/extension-sdk").MemoryPluginDescriptor;
22
22
  declare function apply(ctx: Context, config?: Config): void;
23
23
  //#endregion
24
- 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 };
24
+ 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 CHANGED
@@ -1,4 +1,4 @@
1
- import { n as RUNTIME_MEMORY_LIMITS, o as MAX_RUNTIME_MEMORY_LIMIT_BYTES, t as RUNTIME_ENTRY_DELIMITER } from "./contracts-BqaPCrGD.js";
1
+ 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";
2
2
  import { createMemoryMutationReceipt, defineMemoryPlugin, defineMemorySource, installMemory, memoryConfigurationDigest, memoryInputRecord, memoryInputStringArray, memoryInputText, truncateMemoryText } from "dsh-mnemon/extension-sdk";
3
3
  import { homedir } from "node:os";
4
4
  import { basename, isAbsolute, join } from "node:path";
@@ -34,6 +34,19 @@ const GIT_BRANCH_TIMEOUT_MS = 2e3;
34
34
  * the directory is not a git working tree, HEAD is detached, or the probe
35
35
  * fails or times out, so callers fall back to the unfiltered view.
36
36
  */
37
+ /**
38
+ * Git takes the repository location from the environment, so a launcher that
39
+ * exports `GIT_DIR` for its own reasons would point this probe at a directory
40
+ * that is not the workspace. The probe runs with those variables removed.
41
+ */
42
+ function gitEnvironment(environment = process.env) {
43
+ const sanitized = {};
44
+ for (const [name, value] of Object.entries(environment)) {
45
+ if (value === void 0 || name.toUpperCase().startsWith("GIT_")) continue;
46
+ sanitized[name] = value;
47
+ }
48
+ return sanitized;
49
+ }
37
50
  function resolveGitBranch(cwd) {
38
51
  const root = cwd?.trim();
39
52
  if (root === void 0 || root === "") return void 0;
@@ -51,7 +64,8 @@ function resolveGitBranch(cwd) {
51
64
  "pipe",
52
65
  "ignore"
53
66
  ],
54
- windowsHide: true
67
+ windowsHide: true,
68
+ env: gitEnvironment()
55
69
  }).trim();
56
70
  return branch === "" ? void 0 : branch;
57
71
  } catch {
@@ -61,9 +75,7 @@ function resolveGitBranch(cwd) {
61
75
  //#endregion
62
76
  //#region src/controller.ts
63
77
  const LOCK_TIMEOUT_MS = 5e3;
64
- const LOCK_STALE_MS = 3e4;
65
78
  const LOCK_RETRY_MS = 20;
66
- const MAX_ENTRY_BYTES = 8192;
67
79
  /** Append to a file that is not a symbolic link; the open fails on one. */
68
80
  function appendWithoutLinks(path, text) {
69
81
  const descriptor = openSync(path, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | (constants.O_NOFOLLOW ?? 0), 384);
@@ -105,7 +117,6 @@ function isTarget(value) {
105
117
  function isImportance(value) {
106
118
  return value === "critical" || value === "normal" || value === "low";
107
119
  }
108
- const RUNTIME_BRANCH_NAME_RE = /^[A-Za-z0-9._/-]+$/u;
109
120
  /** Validate a model-supplied branch scope. Returns the normalized list; an empty list means "no scope". */
110
121
  function normalizeRuntimeBranches(value, field = "branches") {
111
122
  if (!Array.isArray(value)) throw new Error(`${field} must be an array of git branch names`);
@@ -114,7 +125,7 @@ function normalizeRuntimeBranches(value, field = "branches") {
114
125
  for (const item of value) {
115
126
  if (typeof item !== "string") throw new Error(`${field} must contain only git branch names`);
116
127
  const branch = item.trim();
117
- 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)`);
128
+ 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)`);
118
129
  if (seen.has(branch)) throw new Error(`${field} must not repeat a branch name`);
119
130
  seen.add(branch);
120
131
  branches.push(branch);
@@ -122,17 +133,6 @@ function normalizeRuntimeBranches(value, field = "branches") {
122
133
  if (branches.length > 16) throw new Error(`${field} supports at most 16 branch names`);
123
134
  return branches;
124
135
  }
125
- /** Parse a stored branch scope. Returns undefined for absent or invalid data. */
126
- function parseRuntimeBranches(value) {
127
- if (value === void 0) return void 0;
128
- if (!Array.isArray(value)) return void 0;
129
- const branches = [];
130
- for (const item of value) {
131
- if (typeof item !== "string" || item === "" || item.length > 128 || !RUNTIME_BRANCH_NAME_RE.test(item)) return void 0;
132
- branches.push(item);
133
- }
134
- return branches;
135
- }
136
136
  function entryMatchesBranch(entry, branch) {
137
137
  return entry.branches === void 0 || entry.branches.length === 0 || entry.branches.includes(branch);
138
138
  }
@@ -145,9 +145,18 @@ function normalizeContent(value, field) {
145
145
  if (content === "") throw new Error(`${field} is required`);
146
146
  if (content.includes("§")) throw new Error(`${field} must not contain the reserved § entry delimiter`);
147
147
  const bytes = Buffer.byteLength(content, "utf8");
148
- if (bytes > MAX_ENTRY_BYTES) throw new Error(`${field} is too large (${bytes} bytes; max ${MAX_ENTRY_BYTES})`);
148
+ if (bytes > 8192) throw new Error(`${field} is too large (${bytes} bytes; max ${RUNTIME_ENTRY_MAX_BYTES})`);
149
149
  return content;
150
150
  }
151
+ function parseOrigin(value) {
152
+ if (!isRecord(value)) return void 0;
153
+ if (typeof value.machine !== "string" || typeof value.label !== "string" || typeof value.at !== "string") return void 0;
154
+ return {
155
+ machine: value.machine,
156
+ label: value.label,
157
+ at: value.at
158
+ };
159
+ }
151
160
  function parseEntry(value) {
152
161
  if (!isRecord(value) || typeof value.content !== "string" || !isTarget(value.target) || !isImportance(value.importance)) return void 0;
153
162
  if (typeof value.created_at !== "string" || typeof value.updated_at !== "string") return void 0;
@@ -155,23 +164,17 @@ function parseEntry(value) {
155
164
  if (content === "" || content.includes("§")) return void 0;
156
165
  if (value.target === "user" && value.branches !== void 0) return void 0;
157
166
  const branches = parseRuntimeBranches(value.branches);
167
+ const origin = parseOrigin(value.origin);
158
168
  return {
159
169
  content,
160
170
  created_at: value.created_at,
161
171
  updated_at: value.updated_at,
162
172
  target: value.target,
163
173
  importance: value.importance,
164
- ...branches === void 0 ? {} : { branches }
174
+ ...branches === void 0 ? {} : { branches },
175
+ ...origin === void 0 ? {} : { origin }
165
176
  };
166
177
  }
167
- function byteCount(entries, target) {
168
- const content = entries.filter((entry) => entry.target === target).map((entry) => entry.content).join(RUNTIME_ENTRY_DELIMITER);
169
- return Buffer.byteLength(content, "utf8");
170
- }
171
- function markdown(entries, target) {
172
- const content = entries.filter((entry) => entry.target === target).map((entry) => entry.content).join(RUNTIME_ENTRY_DELIMITER);
173
- return content === "" ? "" : `${content}\n`;
174
- }
175
178
  function age(timestamp, projectedAt) {
176
179
  const time = Date.parse(timestamp);
177
180
  if (!Number.isFinite(time)) return "unknown";
@@ -352,14 +355,14 @@ var RuntimeMemoryController = class RuntimeMemoryController {
352
355
  memory: limits.memory,
353
356
  user: limits.user
354
357
  };
355
- this.directory = join(runner.effectiveDataDir(), "runtime");
356
- this.sourcePath = join(this.directory, "memories.json");
357
- this.memoryPath = join(this.directory, "MEMORY.md");
358
- this.localUserPath = join(this.directory, "USER.md");
359
- this.lockPath = join(this.directory, ".memories.lock");
360
- this.archivePath = join(this.directory, "archived", "MEMORY.md");
361
- this.archiveSourcePath = join(this.directory, "archived", "memories.jsonl");
362
- const userDirectory = userRunner === void 0 ? this.directory : join(userRunner.effectiveDataDir(), "runtime");
358
+ this.directory = join(runner.effectiveDataDir(), RUNTIME_DIRECTORY);
359
+ this.sourcePath = join(this.directory, RUNTIME_MEMORIES_FILE);
360
+ this.memoryPath = join(this.directory, RUNTIME_PROJECTION_FILES.memory);
361
+ this.localUserPath = join(this.directory, RUNTIME_PROJECTION_FILES.user);
362
+ this.lockPath = join(this.directory, RUNTIME_LOCK_FILE);
363
+ this.archivePath = join(this.directory, RUNTIME_ARCHIVE_DIRECTORY, "MEMORY.md");
364
+ this.archiveSourcePath = join(this.directory, RUNTIME_ARCHIVE_DIRECTORY, "memories.jsonl");
365
+ const userDirectory = userRunner === void 0 ? this.directory : join(userRunner.effectiveDataDir(), RUNTIME_DIRECTORY);
363
366
  this.userController = userDirectory === this.directory || userRunner === void 0 ? void 0 : new RuntimeMemoryController(userRunner, now, this.limits);
364
367
  this.userPath = this.userController?.userPath ?? this.localUserPath;
365
368
  this.userSourcePath = this.userController?.sourcePath ?? this.sourcePath;
@@ -474,8 +477,8 @@ ${memory || "(empty)"}
474
477
  const operation = this.queue.then(() => this.withLock(() => {
475
478
  const file = this.readSource();
476
479
  const prepared = prepareMutation(file.entries, request, this.now().toISOString());
477
- const used = byteCount(file.entries, request.target);
478
- const projected = byteCount(prepared.projectedEntries, request.target);
480
+ const used = runtimeBytes(file.entries, request.target);
481
+ const projected = runtimeBytes(prepared.projectedEntries, request.target);
479
482
  const limit = this.limits[request.target];
480
483
  return {
481
484
  revision: revision(file),
@@ -519,9 +522,9 @@ ${memory || "(empty)"}
519
522
  const fitted = packCompactionCandidates(replacements, request.target, compactedByteBudget);
520
523
  const targetEntries = [...fitted, ...prepared.pendingEntry === void 0 ? [] : [prepared.pendingEntry]];
521
524
  const entries = [...file.entries.filter((entry) => entry.target !== request.target), ...targetEntries];
522
- const used = byteCount(entries, request.target);
525
+ const used = runtimeBytes(entries, request.target);
523
526
  const limit = this.limits[request.target];
524
- if (used > limit) throw new RuntimeMemoryCapacityError(request.target, byteCount(file.entries, request.target), used, limit);
527
+ if (used > limit) throw new RuntimeMemoryCapacityError(request.target, runtimeBytes(file.entries, request.target), used, limit);
525
528
  const next = {
526
529
  version: 1,
527
530
  entries
@@ -543,7 +546,7 @@ ${memory || "(empty)"}
543
546
  }
544
547
  /** Append entries to the local archive: JSON Lines to restore from, and Markdown to read. */
545
548
  archiveLocally(entries, fromRevision, archivedAt) {
546
- const directory = join(this.directory, "archived");
549
+ const directory = join(this.directory, RUNTIME_ARCHIVE_DIRECTORY);
547
550
  mkdirSync(directory, {
548
551
  recursive: true,
549
552
  mode: 448
@@ -581,9 +584,9 @@ ${memory || "(empty)"}
581
584
  const file = this.readSource();
582
585
  const prepared = prepareMutation(file.entries, request, this.now().toISOString());
583
586
  if (!prepared.changed) return this.result(request.target, prepared.projectedEntries, prepared.fields);
584
- const used = byteCount(prepared.projectedEntries, request.target);
587
+ const used = runtimeBytes(prepared.projectedEntries, request.target);
585
588
  const limit = this.limits[request.target];
586
- if (used > limit) throw new RuntimeMemoryCapacityError(request.target, byteCount(file.entries, request.target), used, limit);
589
+ if (used > limit) throw new RuntimeMemoryCapacityError(request.target, runtimeBytes(file.entries, request.target), used, limit);
587
590
  this.persist({
588
591
  version: 1,
589
592
  entries: prepared.projectedEntries
@@ -597,7 +600,7 @@ ${memory || "(empty)"}
597
600
  target,
598
601
  entryCount: entries.filter((entry) => entry.target === target).length,
599
602
  usage: {
600
- used: byteCount(entries, target),
603
+ used: runtimeBytes(entries, target),
601
604
  limit: this.limits[target]
602
605
  },
603
606
  ...fields.added === void 0 ? {} : { added: fields.added },
@@ -609,7 +612,7 @@ ${memory || "(empty)"}
609
612
  return {
610
613
  target,
611
614
  entryCount: entries.filter((entry) => entry.target === target).length,
612
- used: byteCount(entries, target),
615
+ used: runtimeBytes(entries, target),
613
616
  limit: this.limits[target],
614
617
  markdownPath: target === "memory" ? this.memoryPath : this.userPath
615
618
  };
@@ -654,8 +657,8 @@ ${memory || "(empty)"}
654
657
  });
655
658
  const nonce = `${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}`;
656
659
  const writes = [
657
- [this.localUserPath, markdown(file.entries, "user")],
658
- [this.memoryPath, markdown(file.entries, "memory")],
660
+ [this.localUserPath, runtimeProjection(file.entries, "user")],
661
+ [this.memoryPath, runtimeProjection(file.entries, "memory")],
659
662
  [this.sourcePath, `${JSON.stringify(file, null, 2)}\n`]
660
663
  ];
661
664
  const temporaries = writes.map(([path]) => join(this.directory, `.${basename(path)}.${nonce}.tmp`));
@@ -671,7 +674,7 @@ ${memory || "(empty)"}
671
674
  }
672
675
  repairProjections(file) {
673
676
  for (const [path, target] of [[this.localUserPath, "user"], [this.memoryPath, "memory"]]) {
674
- const expected = markdown(file.entries, target);
677
+ const expected = runtimeProjection(file.entries, target);
675
678
  let current;
676
679
  try {
677
680
  current = readFileSync(path, "utf8");
@@ -699,7 +702,7 @@ ${memory || "(empty)"}
699
702
  } catch (error) {
700
703
  if ((isRecord(error) && typeof error.code === "string" ? error.code : void 0) !== "EEXIST") throw error;
701
704
  try {
702
- if (Date.now() - statSync(this.lockPath).mtimeMs > LOCK_STALE_MS) {
705
+ if (Date.now() - statSync(this.lockPath).mtimeMs > 3e4) {
703
706
  rmSync(this.lockPath, { force: true });
704
707
  continue;
705
708
  }
@@ -1,6 +1,12 @@
1
1
  export type RuntimeMemoryTarget = 'memory' | 'user';
2
2
  export type RuntimeMemoryImportance = 'critical' | 'normal' | 'low';
3
3
  export type RuntimeMemoryAction = 'add' | 'replace' | 'remove';
4
+ /** Provenance a DSH Host stamps when an entry crosses machines; absent for local writes. */
5
+ export interface RuntimeMemoryEntryOrigin {
6
+ machine: string;
7
+ label: string;
8
+ at: string;
9
+ }
4
10
  export interface RuntimeMemoryEntry {
5
11
  content: string;
6
12
  created_at: string;
@@ -9,6 +15,8 @@ export interface RuntimeMemoryEntry {
9
15
  importance: RuntimeMemoryImportance;
10
16
  /** Optional git branch names that limit where this entry is projected. Absent means every branch. */
11
17
  branches?: string[];
18
+ /** Which installation wrote this entry, so a merge can tell two machines apart. */
19
+ origin?: RuntimeMemoryEntryOrigin;
12
20
  }
13
21
  export interface RuntimeMemoryUsage {
14
22
  used: number;
@@ -88,3 +96,52 @@ export interface RuntimeMemoryLimits {
88
96
  readonly user: number;
89
97
  }
90
98
  export declare const RUNTIME_MEMORY_LIMITS: RuntimeMemoryLimits;
99
+ /** The largest limit, in UTF-8 bytes, either target's file may be given. */
100
+ export declare const RUNTIME_MEMORY_LIMIT_MAX_BYTES: number;
101
+ /** The longest git branch name a scope may hold. */
102
+ export declare const RUNTIME_BRANCH_NAME_MAX = 128;
103
+ /** The characters a git branch name in a scope may use. */
104
+ export declare const RUNTIME_BRANCH_NAME_PATTERN: RegExp;
105
+ /**
106
+ * Read a stored branch scope. Absent or malformed data reads as no scope, so an entry that
107
+ * a hand edit or another installation left malformed is projected on every branch instead
108
+ * of breaking the projection that reads it.
109
+ */
110
+ export declare function parseRuntimeBranches(value: unknown): string[] | undefined;
111
+ /** The Runtime Source's directory under a storage root. */
112
+ export declare const RUNTIME_DIRECTORY = "runtime";
113
+ /** The entries themselves, the source of truth the projections are written from. */
114
+ export declare const RUNTIME_MEMORIES_FILE = "memories.json";
115
+ /** Each target's projection: its entries' plain content, the file a person reads. */
116
+ export declare const RUNTIME_PROJECTION_FILES: {
117
+ readonly user: "USER.md";
118
+ readonly memory: "MEMORY.md";
119
+ };
120
+ /** Created exclusively while the files above are read or written; whoever copies them takes it too. */
121
+ export declare const RUNTIME_LOCK_FILE = ".memories.lock";
122
+ /** A lock file older than this was left by a process that stopped, and may be taken over. */
123
+ export declare const RUNTIME_LOCK_STALE_MS = 30000;
124
+ /** The local archive of entries that left MEMORY.md while no Memory Space could take them (#336). */
125
+ export declare const RUNTIME_ARCHIVE_DIRECTORY = "archived";
126
+ /** The longest content one entry may hold, in UTF-8 bytes. */
127
+ export declare const RUNTIME_ENTRY_MAX_BYTES: number;
128
+ type RuntimeEntryText = Pick<RuntimeMemoryEntry, 'target' | 'content'>;
129
+ /** The UTF-8 bytes one target's entries take against its limit: their contents joined by the delimiter. */
130
+ export declare function runtimeBytes(entries: ReadonlyArray<RuntimeEntryText>, target: RuntimeMemoryTarget): number;
131
+ /** One target's projection file, USER.md or MEMORY.md, exactly as the Runtime Source writes it. */
132
+ export declare function runtimeProjection(entries: ReadonlyArray<RuntimeEntryText>, target: RuntimeMemoryTarget): string;
133
+ /** What a stored memories.json holds, counted without judging each entry. */
134
+ export interface RuntimeMemoriesSummary {
135
+ /** Whether the file has an entry list at all. Without one, every count is 0. */
136
+ valid: boolean;
137
+ /** Every entry that is an object, whatever its target. */
138
+ entries: number;
139
+ user: number;
140
+ memory: number;
141
+ }
142
+ /**
143
+ * Count the entries of a parsed memories.json for a read-only inventory. It never throws: a file
144
+ * without an entry list is not `valid`, and a malformed entry is counted or skipped, never refused.
145
+ */
146
+ export declare function summarizeRuntimeMemories(value: unknown): RuntimeMemoriesSummary;
147
+ export {};
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-mnemon-source-runtime",
3
- "version": "0.5.13",
3
+ "version": "0.5.15",
4
4
  "description": "Self-contained runtime Source for Composable View Memory.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -55,12 +55,12 @@
55
55
  "react": "^18.2.0"
56
56
  },
57
57
  "devDependencies": {
58
- "@deepseek-ai/dsh-client-ui-primitives": "0.1.7-rc.2",
58
+ "@deepseek-ai/dsh-client-ui-primitives": "0.2.1-rc.2",
59
59
  "@testing-library/react": "^16.3.0",
60
60
  "@types/node": "^22.0.0",
61
61
  "@types/react": "^18.3.0",
62
62
  "@types/react-dom": "^18.3.0",
63
- "dsh-mnemon": "^0.5.25",
63
+ "dsh-mnemon": "^0.5.32",
64
64
  "jsdom": "^26.0.0",
65
65
  "react": "^18.2.0",
66
66
  "react-dom": "^18.2.0",
@@ -84,9 +84,9 @@
84
84
  "micromark-util-sanitize-uri": "^2.0.1",
85
85
  "micromark-util-symbol": "^2.0.1",
86
86
  "shiki": "^4.3.1",
87
- "@deepseek-ai/dsh-client-store": "0.1.7-rc.2",
88
- "@deepseek-ai/dsh-util-code-language": "0.1.7-rc.2",
89
- "@deepseek-ai/dsh-util-workspace-path": "0.1.7-rc.2",
87
+ "@deepseek-ai/dsh-client-store": "0.2.1-rc.2",
88
+ "@deepseek-ai/dsh-util-code-language": "0.2.1-rc.2",
89
+ "@deepseek-ai/dsh-util-workspace-path": "0.2.1-rc.2",
90
90
  "diff": "^9.0.0",
91
91
  "immer": "^10.1.1",
92
92
  "simple-icons": "16.31.0",
@@ -1,14 +0,0 @@
1
- //#region src/defaults.ts
2
- const DEFAULT_RUNTIME_MEMORY_LIMIT_BYTES = 10240;
3
- const DEFAULT_RUNTIME_USER_LIMIT_BYTES = 4096;
4
- const MAX_RUNTIME_MEMORY_LIMIT_BYTES = 1048576;
5
- //#endregion
6
- //#region src/contracts.ts
7
- const RUNTIME_MEMORY_VERSION = 1;
8
- const RUNTIME_ENTRY_DELIMITER = "\n§\n";
9
- const RUNTIME_MEMORY_LIMITS = {
10
- memory: DEFAULT_RUNTIME_MEMORY_LIMIT_BYTES,
11
- user: DEFAULT_RUNTIME_USER_LIMIT_BYTES
12
- };
13
- //#endregion
14
- 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 };