@staix/vault-mem 0.9.1 → 0.10.1

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.
Files changed (49) hide show
  1. package/CHANGELOG.md +31 -0
  2. package/README.md +19 -6
  3. package/bin/vmem.js +2 -2
  4. package/package.json +2 -2
  5. package/src/analysis-commands.ts +24 -14
  6. package/src/analysis-input.ts +12 -0
  7. package/src/analysis-types.ts +5 -1
  8. package/src/assert-command.ts +48 -0
  9. package/src/assertion-exposure.ts +367 -0
  10. package/src/assertion-index.ts +86 -0
  11. package/src/assertion-policy.ts +63 -0
  12. package/src/assertion-read.ts +170 -0
  13. package/src/assertions-command.ts +123 -0
  14. package/src/assertions.ts +1013 -0
  15. package/src/cli-output.ts +9 -3
  16. package/src/cli.ts +44 -23
  17. package/src/commands-table.ts +16 -2
  18. package/src/evidence.ts +222 -0
  19. package/src/graph-evidence.ts +169 -0
  20. package/src/index.ts +14 -0
  21. package/src/links.ts +18 -0
  22. package/src/log-commands.ts +7 -7
  23. package/src/mcp-spec.ts +11 -11
  24. package/src/mcp-vault.ts +105 -6
  25. package/src/mcp.ts +4 -0
  26. package/src/org-commands.ts +5 -5
  27. package/src/org-promote.ts +9 -0
  28. package/src/promote-command.ts +6 -6
  29. package/src/proposal-commands.ts +100 -0
  30. package/src/proposal-provider.ts +335 -0
  31. package/src/proposal-storage.ts +334 -0
  32. package/src/proposals.ts +170 -0
  33. package/src/read-commands.ts +44 -12
  34. package/src/read-output.ts +42 -14
  35. package/src/skills-mine.ts +12 -7
  36. package/src/source-age.ts +131 -0
  37. package/src/spec-output.ts +14 -13
  38. package/src/sync.ts +14 -7
  39. package/src/text-output.ts +86 -21
  40. package/src/vault-brief.ts +8 -4
  41. package/src/vault-graph.ts +12 -3
  42. package/src/vault-history.ts +662 -0
  43. package/src/vault-index.ts +2 -0
  44. package/src/vault-lint.ts +15 -4
  45. package/src/write-commands.ts +18 -17
  46. package/src/write-output.ts +6 -6
  47. package/src/write-types.ts +1 -0
  48. package/src/write-validation.ts +3 -1
  49. package/src/writer.ts +257 -11
@@ -0,0 +1,1013 @@
1
+ /**
2
+ * Append-only assertion journal (issue 250; design `docs/specs/2026-11-19-temporal-assertions-design.md`).
3
+ *
4
+ * Segments `assertions/<16 hex>.jsonl` hold canonical JSON lines chained by `prev`/`hash`. One clone appends one
5
+ * segment, tracked in `<VMEM_HOME>/assertion-writers/<vault-id>.json`. `readJournal` verifies segments,
6
+ * `evaluateAssertions` is the pure evaluation the read surface wraps, and `appendAssertions` is the write contract.
7
+ * Nothing here writes a note, an `updated` stamp or a log line unless the caller supplies a log event.
8
+ */
9
+ import { randomBytes } from "node:crypto";
10
+ import { closeSync, constants, fstatSync, fsyncSync, ftruncateSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, renameSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
11
+ import { hostname } from "node:os";
12
+ import { join, resolve } from "node:path";
13
+ import { assertionIndexPath, rebuildAssertionIndex } from "./assertion-index.ts";
14
+ import { unenforceablePii, type VaultSpec, type VmemConfig } from "./config.ts";
15
+ import { parseEvidence, verifyEvidenceEntry, type EvidenceEntry, type EvidenceReads } from "./evidence.ts";
16
+ import { AGENT_MARKERS } from "./log-format.ts";
17
+ import type { LogEvent, LogReceipt } from "./log-types.ts";
18
+ import { canonicalPath, isDenied } from "./platform.ts";
19
+ import { loadRegistry, syncDirectory } from "./registry.ts";
20
+ import { sourceReferences, sourceWorkspaceRoot } from "./source.ts";
21
+ import { appendLog, checkLogEvent } from "./vault-log.ts";
22
+ import { screenContent, screenMetadata } from "./write-validation.ts";
23
+ import type { WriteIssue } from "./write-types.ts";
24
+ import { shellWord } from "./text-output.ts";
25
+ import { canonical, sha256 } from "./writer.ts";
26
+
27
+ export const ASSERTIONS_DIR = "assertions";
28
+ export const ASSERTIONS_LOCK = "assertions.lock";
29
+ export const ASSERTION_SCHEMA_VERSION = 1;
30
+ export const MAX_BATCH_OPS = 32, MAX_BATCH_BYTES = 64 * 1024, MAX_PAYLOAD_BYTES = 16 * 1024, MAX_VALUE_BYTES = 1024, MAX_LABEL_CHARS = 200;
31
+ export const MAX_SEGMENT_BYTES = 8 * 1024 * 1024, MAX_JOURNAL_BYTES = 64 * 1024 * 1024, MAX_JOURNAL_ENTRIES = 100_000;
32
+ /** UTF-16 units of a purge reason: the same limit the verifier applies, so an accepted reason always verifies. */
33
+ export const MAX_PURGE_REASON = 200;
34
+ /** Bound of a complete `vmem_assert` request or reply, measured as the encoded JSON-RPC frame. */
35
+ export const ASSERT_FRAME_BYTES = 48 * 1024;
36
+ const ENVELOPE_ID_BYTES = 128;
37
+ /** Bytes of `value` as a complete JSON-RPC frame (128-byte id, MCP text content, newline), as `src/graph-evidence.ts#encodedBytes`. */
38
+ export function assertFrameBytes(value: unknown, kind: "request" | "result" = "request"): number {
39
+ const frame = kind === "request" ? { jsonrpc: "2.0", id: "x".repeat(ENVELOPE_ID_BYTES), method: "tools/call", params: { name: "vmem_assert", arguments: value } }
40
+ : { jsonrpc: "2.0", id: "x".repeat(ENVELOPE_ID_BYTES), result: { content: [{ type: "text", text: JSON.stringify(value) }] } };
41
+ return Buffer.byteLength(JSON.stringify(frame)) + 1;
42
+ }
43
+ const ZERO = "0".repeat(64);
44
+ const SEGMENT = /^[0-9a-f]{16}$/, INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/, HEX64 = /^[0-9a-f]{64}$/;
45
+ const SUBJECT = /^s:[a-z0-9][a-z0-9-]{0,63}$/, RELATION = /^[a-z0-9][a-z0-9-]{0,63}$/, ASSERTION_ID = /^a:[0-9a-f]{16}:[1-9][0-9]{0,8}$/;
46
+ const REASONS = ["recorded_in_error", "evidence_withdrawn", "other"] as const;
47
+
48
+ // ---------------------------------------------------------------- types
49
+
50
+ export type EntryOp = "subject" | "assert" | "revise" | "retract";
51
+ export interface JournalEntry {
52
+ v: number; seg: string; seq: number; prev: string; hash: string; payload_sha256: string; recorded_at: string;
53
+ channel: "cli" | "mcp"; actor: "person" | "agent"; op: EntryOp; batch: { id: string; size: number; index: number };
54
+ parents?: string[]; payload?: Record<string, unknown>; purged?: { at: string; reason: string };
55
+ }
56
+ export interface SegmentReport {
57
+ segment: string;
58
+ entries: JournalEntry[];
59
+ /** Last verified (seq, hash), or null for an empty or wholly untrusted segment. */
60
+ tail: { seq: number; hash: string; recordedAt: string } | null;
61
+ /** Byte length of the verified prefix (complete batches only). */
62
+ verifiedBytes: number;
63
+ size: number;
64
+ tornTail: boolean;
65
+ partialBatch: { seq: number } | null;
66
+ untrusted: { seq: number; reason: string } | null;
67
+ unsupported: { seq: number; version: unknown } | null;
68
+ }
69
+ export interface VerifiedJournal { present: boolean; segments: SegmentReport[]; ignored: string[]; bytes: number; entries: number }
70
+
71
+ export interface AssertionQuery { at?: string; asOf?: string; subject?: string; relation?: string; history?: boolean }
72
+ export type Answer = "yes" | "no" | "unknown";
73
+ export interface AssertionItem {
74
+ id: string; rev: number; op: "assert" | "revise" | "retract"; subject: string; relation: string; hash: string;
75
+ value?: string; kind?: "state" | "event"; from?: string; to?: string; held_on?: string; on?: string; reason?: string;
76
+ evidence?: unknown[]; source?: string[];
77
+ answer?: Answer; recordedAt: string; effectiveRecordedAt?: string; clockInverted?: true; replacedAt?: string | null;
78
+ revisionConflict?: true; heads?: string[]; purged?: true;
79
+ segment?: string; seq?: number;
80
+ }
81
+ export interface AssertionAnswerSet {
82
+ schemaVersion: 1;
83
+ at: string | null;
84
+ asOf: { requested: string; cutoff: string; cutoffInclusive: boolean } | null;
85
+ pin: { segment: string; seq: number; hash: string }[];
86
+ coverage: {
87
+ journal: "present" | "absent"; beforeFirstEntry: boolean;
88
+ untrusted: { segment: string; seq: number; reason: string }[]; unsupported: { segment: string; seq: number }[];
89
+ tornTail: string[]; partialBatch: { segment: string; seq: number }[]; purged: number;
90
+ };
91
+ items: AssertionItem[];
92
+ overlaps: { subject: string; relation: string; ids: string[]; possible?: true }[];
93
+ }
94
+
95
+ // ---------------------------------------------------------------- hashing and dates
96
+
97
+ /** The chained hash: SHA-256 of the canonical entry without `hash`, `payload` and `purged`. */
98
+ export function entryHash(entry: Omit<JournalEntry, "hash"> & { hash?: string }): string {
99
+ const { hash: _h, payload: _p, purged: _x, ...hashed } = entry;
100
+ return sha256(canonical(hashed));
101
+ }
102
+ export const payloadHash = (payload: unknown) => sha256(canonical(payload));
103
+
104
+ /** Days since 1970-01-01 in the proleptic Gregorian calendar (Hinnant's days_from_civil), valid for years 1..9999. */
105
+ function days(y: number, m: number, d: number): number {
106
+ const yy = m <= 2 ? y - 1 : y, era = Math.floor(yy / 400), yoe = yy - era * 400;
107
+ const doy = Math.floor((153 * (m + (m > 2 ? -3 : 9)) + 2) / 5) + d - 1, doe = yoe * 365 + Math.floor(yoe / 4) - Math.floor(yoe / 100) + doy;
108
+ return era * 146097 + doe - 719468;
109
+ }
110
+ const monthDays = (y: number, m: number) => m === 2 ? ((y % 4 === 0 && y % 100 !== 0) || y % 400 === 0 ? 29 : 28) : [4, 6, 9, 11].includes(m) ? 30 : 31;
111
+ /** A date value `YYYY`, `YYYY-MM` or `YYYY-MM-DD` as its first and last candidate day, or undefined when invalid. */
112
+ export function dateRange(value: unknown): [number, number] | undefined {
113
+ if (typeof value !== "string") return undefined;
114
+ const match = /^(\d{4})(?:-(\d{2})(?:-(\d{2}))?)?$/.exec(value);
115
+ if (!match) return undefined;
116
+ const y = Number(match[1]), m = match[2] === undefined ? undefined : Number(match[2]), d = match[3] === undefined ? undefined : Number(match[3]);
117
+ if (y < 1 || (m !== undefined && (m < 1 || m > 12)) || (m !== undefined && d !== undefined && (d < 1 || d > monthDays(y, m)))) return undefined;
118
+ if (m === undefined) return [days(y, 1, 1), days(y, 12, 31)];
119
+ if (d === undefined) return [days(y, m, 1), days(y, m, monthDays(y, m))];
120
+ return [days(y, m, d), days(y, m, d)];
121
+ }
122
+ const day = (value: unknown): number | undefined => typeof value === "string" && /^\d{4}-\d{2}-\d{2}$/.test(value) ? dateRange(value)?.[0] : undefined;
123
+ function validInstant(value: unknown): value is string {
124
+ if (typeof value !== "string" || !INSTANT.test(value)) return false;
125
+ const parsed = new Date(value);
126
+ return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 19) + "Z" === value;
127
+ }
128
+ const instant = (date: Date) => date.toISOString().slice(0, 19) + "Z";
129
+
130
+ interface Bounds { sLo: number; sHi: number; eLo: number; eHi: number }
131
+ /** State bounds after the `held_on` and start-before-end constraints, or a refusal reason. */
132
+ function stateBounds(from: unknown, to: unknown, heldOn: unknown): Bounds | string {
133
+ const start = from === "unknown" ? [-Infinity, Infinity] : dateRange(from);
134
+ if (!start) return "from must be a date value YYYY, YYYY-MM or YYYY-MM-DD, or unknown; write from as one of those";
135
+ const end = to === "open" ? [Infinity, Infinity] : to === "unknown" ? [-Infinity, Infinity] : dateRange(to);
136
+ if (!end) return "to must be a date value, unknown or open; write to as a date, open or unknown";
137
+ let [sLo, sHi] = start as [number, number], [eLo, eHi] = end as [number, number];
138
+ if (heldOn !== undefined) {
139
+ const h = day(heldOn);
140
+ if (h === undefined) return "held_on must be a day YYYY-MM-DD; write the day the value was observed";
141
+ sHi = Math.min(sHi, h); eLo = Math.max(eLo, h + 1);
142
+ }
143
+ sHi = Math.min(sHi, eHi - 1); eLo = Math.max(eLo, sLo + 1);
144
+ if (sLo > sHi || eLo > eHi) return "the bounds leave no start before end; check from, to and held_on";
145
+ if (from === "unknown" && to !== undefined && (to === "unknown" || to === "open") && heldOn === undefined) return "a state with unknown from and unknown or open to is unknown on every day; give held_on or a bound";
146
+ return { sLo, sHi, eLo, eHi };
147
+ }
148
+ /** The answer of one revision on day `t` (precision section of the design). */
149
+ export function answerOn(payload: Record<string, unknown>, t: number): Answer {
150
+ if (payload.kind === "event") {
151
+ const range = dateRange(payload.on);
152
+ if (!range) return "unknown";
153
+ return range[1] <= t ? "yes" : t < range[0] ? "no" : "unknown";
154
+ }
155
+ const bounds = stateBounds(payload.from, payload.to, payload.held_on);
156
+ if (typeof bounds === "string") return "unknown";
157
+ if (bounds.sHi <= t && bounds.eLo > t) return "yes";
158
+ return bounds.sLo <= t && bounds.eHi > t ? "unknown" : "no";
159
+ }
160
+
161
+ // ---------------------------------------------------------------- verification
162
+
163
+ const ENTRY_KEYS = new Set(["v", "seg", "seq", "prev", "hash", "payload_sha256", "recorded_at", "channel", "actor", "op", "batch", "parents", "payload", "purged"]);
164
+ /** A purge marker is exactly `{at, reason}` and never travels with a payload, because neither is inside the hash. */
165
+ function purgeShape(value: unknown): string | undefined {
166
+ if (!value || typeof value !== "object" || Array.isArray(value)) return "invalid purged";
167
+ const marker = value as Record<string, unknown>;
168
+ if (Object.keys(marker).some(key => key !== "at" && key !== "reason")) return "invalid purged";
169
+ if (typeof marker.at !== "string" || !validInstant(marker.at)) return "invalid purged";
170
+ if (typeof marker.reason !== "string" || !marker.reason || marker.reason.length > MAX_PURGE_REASON || /\p{Cc}/u.test(marker.reason)) return "invalid purged";
171
+ return undefined;
172
+ }
173
+ function shapeProblem(entry: Record<string, unknown>): string | undefined {
174
+ for (const key of Object.keys(entry)) if (!ENTRY_KEYS.has(key)) return `unknown key ${key.slice(0, 32)}`;
175
+ if (!["cli", "mcp"].includes(entry.channel as string) || !["person", "agent"].includes(entry.actor as string)) return "invalid channel or actor";
176
+ if (!["subject", "assert", "revise", "retract"].includes(entry.op as string)) return "invalid op";
177
+ const batch = entry.batch as Record<string, unknown> | undefined;
178
+ if (!batch || typeof batch !== "object" || typeof batch.id !== "string" || !Number.isSafeInteger(batch.size) || !Number.isSafeInteger(batch.index)) return "invalid batch";
179
+ if (!HEX64.test(String(entry.payload_sha256)) || !HEX64.test(String(entry.prev)) || !HEX64.test(String(entry.hash))) return "invalid hash field";
180
+ const revision = entry.op === "revise" || entry.op === "retract";
181
+ if (revision !== Array.isArray(entry.parents) || (revision && (!(entry.parents as unknown[]).length || (entry.parents as unknown[]).some(p => typeof p !== "string" || !HEX64.test(p))))) return "invalid parents";
182
+ if (entry.purged !== undefined) {
183
+ if (entry.payload !== undefined) return "a purged entry still carries a payload";
184
+ return purgeShape(entry.purged);
185
+ }
186
+ if (!entry.payload || typeof entry.payload !== "object" || Array.isArray(entry.payload)) return "missing payload";
187
+ if (revision && typeof (entry.payload as Record<string, unknown>).id !== "string") return "missing payload id";
188
+ return undefined;
189
+ }
190
+ /** The assertion an entry belongs to: its own `a:seg:seq` for an assert, the named id for a revision. */
191
+ const assertionOf = (entry: JournalEntry) => entry.op === "assert" ? `a:${entry.seg}:${entry.seq}` : typeof entry.payload?.id === "string" ? entry.payload.id : undefined;
192
+ /** Both caps are checked against the size from `fstat` before any byte is read, so a refusal never reads a budget over. */
193
+ function readBounded(file: string, limit: number, remaining = Infinity): Buffer | "too_large" | "over_total" | "not_a_file" {
194
+ let fd: number;
195
+ try { fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
196
+ catch (caught) {
197
+ // A link is never read or replaced: the segment is reported as ignored, and an append names it.
198
+ if (["ELOOP", "EMLINK"].includes((caught as NodeJS.ErrnoException).code ?? "")) return "not_a_file";
199
+ throw caught;
200
+ }
201
+ try {
202
+ const stat = fstatSync(fd);
203
+ if (!stat.isFile()) return "not_a_file";
204
+ if (stat.size > limit) return "too_large";
205
+ if (stat.size > remaining) return "over_total";
206
+ const buffer = Buffer.alloc(stat.size); let read = 0;
207
+ while (read < stat.size) { const n = readSync(fd, buffer, read, stat.size - read, null); if (!n) break; read += n; }
208
+ return buffer.subarray(0, read);
209
+ } finally { closeSync(fd); }
210
+ }
211
+ /** Verify one segment's bytes (design: Evaluation step 1). Pure over the bytes. */
212
+ export function verifySegment(segment: string, bytes: Buffer): SegmentReport {
213
+ const report: SegmentReport = { segment, entries: [], tail: null, verifiedBytes: 0, size: bytes.length, tornTail: false, partialBatch: null, untrusted: null, unsupported: null };
214
+ let offset = 0, prev = ZERO, last = "", pending: { entry: JournalEntry; end: number }[] = [];
215
+ const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
216
+ while (offset < bytes.length) {
217
+ const newline = bytes.indexOf(10, offset);
218
+ if (newline < 0) { report.tornTail = true; break; }
219
+ const seq = report.entries.length + pending.length + 1, raw = bytes.subarray(offset, newline);
220
+ const fail = (reason: string) => { report.untrusted = { seq, reason }; };
221
+ let entry: JournalEntry;
222
+ try {
223
+ const text = decoder.decode(raw), parsed = JSON.parse(text) as Record<string, unknown>;
224
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) { fail("not an object"); break; }
225
+ if (parsed.v !== ASSERTION_SCHEMA_VERSION) { report.unsupported = { seq, version: parsed.v }; break; }
226
+ if (canonical(parsed) !== text) { fail("not canonical JSON"); break; }
227
+ const problem = shapeProblem(parsed);
228
+ if (problem) { fail(problem); break; }
229
+ entry = parsed as unknown as JournalEntry;
230
+ } catch { fail("invalid JSON or UTF-8"); break; }
231
+ if (entry.seg !== segment) { fail("segment id differs from the file name"); break; }
232
+ if (entry.seq !== seq) { fail("seq is not contiguous"); break; }
233
+ if (entry.prev !== prev) { fail("prev does not match the previous hash"); break; }
234
+ if (entryHash(entry) !== entry.hash) { fail("hash mismatch"); break; }
235
+ if (entry.purged === undefined && payloadHash(entry.payload) !== entry.payload_sha256) { fail("payload_sha256 mismatch"); break; }
236
+ if (!validInstant(entry.recorded_at) || entry.recorded_at < last) { fail("recorded_at is invalid or earlier than the previous entry"); break; }
237
+ // Batch framing: index 0 opens a batch whose id names its first seq; later entries continue it in order.
238
+ const open = pending[0]?.entry.batch;
239
+ if (entry.batch.index === 0 ? pending.length !== 0 || entry.batch.id !== `${segment}:${seq}` || entry.batch.size < 1 || entry.batch.size > MAX_BATCH_OPS
240
+ : !open || entry.batch.id !== open.id || entry.batch.size !== open.size || entry.batch.index !== pending.length || entry.recorded_at !== pending[0]!.entry.recorded_at) {
241
+ // An interrupted batch followed by a new one: the earlier batch is partial and the chain after it is untrusted.
242
+ fail("batch framing is broken"); break;
243
+ }
244
+ prev = entry.hash; last = entry.recorded_at; offset = newline + 1;
245
+ pending.push({ entry, end: offset });
246
+ if (pending.length === entry.batch.size) {
247
+ report.entries.push(...pending.map(item => item.entry)); report.verifiedBytes = offset; pending = [];
248
+ }
249
+ }
250
+ if (pending.length && !report.untrusted && !report.unsupported) report.partialBatch = { seq: pending[0]!.entry.seq };
251
+ else if (pending.length && report.untrusted) report.untrusted = { seq: pending[0]!.entry.seq, reason: report.untrusted.reason };
252
+ const tail = report.entries.at(-1);
253
+ if (tail) report.tail = { seq: tail.seq, hash: tail.hash, recordedAt: tail.recorded_at };
254
+ return report;
255
+ }
256
+ /** Read and verify every segment of a vault. Refuses (throws V09) beyond the journal bound instead of reading partial history. */
257
+ export function readJournal(vaultPath: string, denyPaths: readonly string[] = []): VerifiedJournal {
258
+ const dir = join(vaultPath, ASSERTIONS_DIR);
259
+ if (isDenied(canonicalPath(dir), [...denyPaths])) throw coded("V06", "the assertions/ path is denied by denyPaths; nothing was read. Remove the deny entry to use assertions in this vault");
260
+ let names: string[];
261
+ try {
262
+ const stat = lstatSync(dir);
263
+ if (stat.isSymbolicLink() || !stat.isDirectory()) throw coded("V04", "assertions/ must be a plain directory, not a link or file; restore it from Git or move it aside");
264
+ names = readdirSync(dir).sort();
265
+ } catch (caught) {
266
+ if ((caught as NodeJS.ErrnoException).code === "ENOENT") return { present: false, segments: [], ignored: [], bytes: 0, entries: 0 };
267
+ throw caught;
268
+ }
269
+ // Every listed file holds at least one entry, so more names than the entry bound is already a journal over its bound.
270
+ if (names.length > MAX_JOURNAL_ENTRIES) throw coded("V09", `${ASSERTIONS_DIR} lists ${names.length} entries, more than the ${MAX_JOURNAL_ENTRIES}-entry journal bound; reads and appends refuse rather than list partial history. Archive old segments with Git outside vmem`);
271
+ const journal: VerifiedJournal = { present: true, segments: [], ignored: [], bytes: 0, entries: 0 };
272
+ for (const name of names) {
273
+ const id = name.endsWith(".jsonl") ? name.slice(0, -6) : "";
274
+ if (!SEGMENT.test(id)) { journal.ignored.push(name); continue; }
275
+ const data = readBounded(join(dir, name), MAX_SEGMENT_BYTES + MAX_BATCH_BYTES * 4, MAX_JOURNAL_BYTES - journal.bytes);
276
+ if (data === "not_a_file") { journal.ignored.push(name); continue; }
277
+ if (data === "too_large") throw coded("V09", `${ASSERTIONS_DIR}/${name} exceeds ${MAX_SEGMENT_BYTES} bytes; reads and appends refuse rather than use partial history. Split the segment with Git outside vmem`);
278
+ if (data === "over_total") throw coded("V09", `the assertion journal exceeds ${MAX_JOURNAL_BYTES} bytes; reads and appends refuse rather than use partial history. Archive old segments with Git outside vmem`);
279
+ const report = verifySegment(id, data);
280
+ journal.bytes += data.length; journal.entries += report.entries.length;
281
+ if (journal.entries > MAX_JOURNAL_ENTRIES) throw coded("V09", `the assertion journal exceeds ${MAX_JOURNAL_ENTRIES} entries; reads and appends refuse rather than use partial history. Archive old segments with Git outside vmem`);
282
+ journal.segments.push(report);
283
+ }
284
+ return journal;
285
+ }
286
+
287
+ // ---------------------------------------------------------------- evaluation
288
+
289
+ /** `depth` is the longest parent chain below the entry, so a parent always sorts before its child. */
290
+ interface Kept { entry: JournalEntry; effective: string; inverted: boolean; depth: number; assertionId?: string }
291
+ interface Resolved { kept: Map<string, Kept>; untrusted: { segment: string; seq: number; reason: string }[] }
292
+ /** Steps 2: effective record times across segments; an entry whose parent is missing, untrusted or foreign is untrusted. */
293
+ function resolveEntries(journal: VerifiedJournal): Resolved {
294
+ const byHash = new Map<string, JournalEntry>();
295
+ for (const segment of journal.segments) for (const entry of segment.entries) byHash.set(entry.hash, entry);
296
+ const done = new Map<string, Kept | string>(), visiting = new Set<string>();
297
+ const resolve = (entry: JournalEntry): Kept | string => {
298
+ const known = done.get(entry.hash);
299
+ if (known !== undefined) return known;
300
+ if (visiting.has(entry.hash)) return "parent cycle in the journal";
301
+ visiting.add(entry.hash);
302
+ let own = assertionOf(entry);
303
+ let effective = entry.recorded_at, depth = 0, failure = "";
304
+ for (const parent of entry.parents ?? []) {
305
+ const found = byHash.get(parent);
306
+ if (!found) { failure = "parent missing from every verified segment"; break; }
307
+ const kept = resolve(found);
308
+ if (typeof kept === "string") { failure = kept; break; }
309
+ // A revision names its own assertion's heads only; a cross-assertion parent would displace another head set.
310
+ if (own !== undefined && kept.assertionId !== own) { failure = "a parent belongs to another assertion"; break; }
311
+ if (own === undefined) own = kept.assertionId;
312
+ if (kept.effective > effective) effective = kept.effective;
313
+ if (kept.depth >= depth) depth = kept.depth + 1;
314
+ }
315
+ visiting.delete(entry.hash);
316
+ const result = failure ? failure : { entry, effective, inverted: effective !== entry.recorded_at, depth, ...(own ? { assertionId: own } : {}) };
317
+ done.set(entry.hash, result);
318
+ return result;
319
+ };
320
+ const kept = new Map<string, Kept>(), untrusted: Resolved["untrusted"] = [];
321
+ for (const segment of journal.segments) for (const entry of segment.entries) {
322
+ const result = resolve(entry);
323
+ if (typeof result === "string") untrusted.push({ segment: entry.seg, seq: entry.seq, reason: result });
324
+ else kept.set(entry.hash, result);
325
+ }
326
+ return { kept, untrusted };
327
+ }
328
+ /** Resolve an `as_of` value to its cutoff (design: `as_of` semantics). */
329
+ export function asOfCutoff(value: string): { requested: string; cutoff: string; cutoffInclusive: boolean } {
330
+ if (validInstant(value)) return { requested: value, cutoff: value, cutoffInclusive: true };
331
+ const start = day(value);
332
+ if (start === undefined || dateRange(value)?.[0] !== start) throw coded("V01", "as_of must be a UTC instant YYYY-MM-DDTHH:MM:SSZ or a date YYYY-MM-DD; pass one of those forms");
333
+ // The day after 9999-12-31 has no four-digit instant, so the last representable day keeps its own last second.
334
+ if (start >= days(9999, 12, 31)) return { requested: value, cutoff: "9999-12-31T23:59:59Z", cutoffInclusive: true };
335
+ const next = new Date(Date.UTC(2000, 0, 1) + (start + 1 - days(2000, 1, 1)) * 86400000);
336
+ return { requested: value, cutoff: instant(next), cutoffInclusive: false };
337
+ }
338
+ interface AssertionState {
339
+ id: string; subject: string; relation: string; entries: Kept[];
340
+ heads: Kept[]; retracted: boolean; purged: boolean;
341
+ }
342
+ function states(kept: Iterable<Kept>): { assertions: Map<string, AssertionState>; subjects: Map<string, Kept> } {
343
+ const assertions = new Map<string, AssertionState>(), subjects = new Map<string, Kept>(), named = new Set<string>();
344
+ const ordered = [...kept].sort(order);
345
+ for (const item of ordered) {
346
+ const { entry } = item;
347
+ if (entry.op === "subject") {
348
+ const subject = entry.payload?.subject;
349
+ if (typeof subject !== "string") continue;
350
+ subjects.set(subject, item);
351
+ for (const parent of entry.parents ?? []) named.add(parent);
352
+ continue;
353
+ }
354
+ const id = item.assertionId;
355
+ if (typeof id !== "string") continue;
356
+ let state = assertions.get(id);
357
+ if (entry.op === "assert") {
358
+ if (state) continue;
359
+ state = { id, subject: String(entry.payload?.subject ?? ""), relation: String(entry.payload?.relation ?? ""), entries: [], heads: [], retracted: false, purged: false };
360
+ assertions.set(id, state);
361
+ }
362
+ if (!state) continue; // a revision whose assertion is outside the cutoff or missing cannot be its own head
363
+ // Only an entry that joins a state displaces its parents from the head set; a dropped one leaves them as heads.
364
+ for (const parent of entry.parents ?? []) named.add(parent);
365
+ state.entries.push(item);
366
+ if (entry.purged) state.purged = true;
367
+ }
368
+ for (const state of assertions.values()) {
369
+ state.heads = state.entries.filter(item => !named.has(item.entry.hash));
370
+ state.retracted = state.heads.length === 1 && state.heads[0]!.entry.op === "retract";
371
+ }
372
+ return { assertions, subjects };
373
+ }
374
+ /** Current subjects attached to one note, computed from verified journal entries. */
375
+ export function subjectsAtNote(journal: VerifiedJournal, note: string): string[] {
376
+ const { subjects } = states(resolveEntries(journal).kept.values());
377
+ return [...subjects].filter(([, value]) => value.entry.payload?.note === note).map(([subject]) => subject).sort();
378
+ }
379
+ /** Causal order: a parent's depth is always below its child's, so an entry is never processed before the one it revises. */
380
+ const order = (a: Kept, b: Kept) => a.effective < b.effective ? -1 : a.effective > b.effective ? 1
381
+ : a.depth !== b.depth ? a.depth - b.depth
382
+ : a.entry.seg < b.entry.seg ? -1 : a.entry.seg > b.entry.seg ? 1 : a.entry.seq - b.entry.seq;
383
+ function item(state: AssertionState, kept: Kept, t: number | undefined): AssertionItem {
384
+ const { entry } = kept, payload = entry.payload ?? {};
385
+ const out: AssertionItem = { id: state.id, rev: entry.op === "assert" ? 1 : entry.purged ? kept.depth + 1 : Number(payload.rev), op: entry.op as AssertionItem["op"], subject: entry.purged ? "" : state.subject, relation: entry.purged ? "" : state.relation, hash: entry.hash, recordedAt: entry.recorded_at };
386
+ if (entry.purged) { out.purged = true; out.segment = entry.seg; out.seq = entry.seq; }
387
+ for (const key of ["value", "kind", "from", "to", "held_on", "on", "reason", "evidence", "source"] as const) if (payload[key] !== undefined) (out as unknown as Record<string, unknown>)[key] = payload[key];
388
+ if (kept.inverted) { out.effectiveRecordedAt = kept.effective; out.clockInverted = true; }
389
+ if (t !== undefined && entry.op !== "retract" && !entry.purged) out.answer = answerOn(payload, t);
390
+ return out;
391
+ }
392
+ /**
393
+ * Pure evaluation over verified segments (design: Evaluation steps 2 to 5 and overlap grouping). No Git, index,
394
+ * network or file access. Current policy is applied by the read surface (#251), not here.
395
+ */
396
+ export function evaluateAssertions(journal: VerifiedJournal, query: AssertionQuery = {}): AssertionAnswerSet {
397
+ const t = query.at === undefined ? undefined : day(query.at);
398
+ if (query.at !== undefined && t === undefined) throw coded("V01", "at must be a civil date YYYY-MM-DD between 0001-01-01 and 9999-12-31; pass a whole day in that range");
399
+ const asOf = query.asOf === undefined ? null : asOfCutoff(query.asOf);
400
+ const resolved = resolveEntries(journal);
401
+ const within = (kept: Kept) => !asOf || (asOf.cutoffInclusive ? kept.effective <= asOf.cutoff : kept.effective < asOf.cutoff);
402
+ const kept = [...resolved.kept.values()].filter(within);
403
+ const { assertions } = states(kept);
404
+ // Purge is a present-day availability constraint, including for earlier record-time queries.
405
+ const purgedIds = new Set([...resolved.kept.values()].filter(k => k.entry.purged && k.assertionId).map(k => k.assertionId!));
406
+ for (const state of assertions.values()) if (purgedIds.has(state.id)) state.purged = true;
407
+ const items: AssertionItem[] = [];
408
+ let purged = 0;
409
+ for (const state of assertions.values()) {
410
+ if (state.purged) purged++;
411
+ if (query.subject !== undefined && state.subject !== query.subject) continue;
412
+ if (query.relation !== undefined && state.relation !== query.relation) continue;
413
+ if (query.history) {
414
+ const replaced = new Map<string, string>();
415
+ for (const k of state.entries) for (const parent of k.entry.parents ?? []) if (!replaced.has(parent)) replaced.set(parent, k.effective);
416
+ for (const k of state.entries) if (!k.entry.purged || (query.subject === undefined && query.relation === undefined)) items.push({ ...item(state, k, t), replacedAt: replaced.get(k.entry.hash) ?? null });
417
+ continue;
418
+ }
419
+ if (state.retracted || state.purged) continue;
420
+ const conflict = state.heads.length > 1, heads = state.heads.map(head => head.entry.hash).sort();
421
+ for (const head of state.heads) {
422
+ if (head.entry.op === "retract" && conflict) continue; // reported through the conflict set, not answered
423
+ items.push({ ...item(state, head, t), ...(conflict ? { revisionConflict: true as const, heads } : {}) });
424
+ }
425
+ }
426
+ items.sort((a, b) => a.subject < b.subject ? -1 : a.subject > b.subject ? 1 : a.relation < b.relation ? -1 : a.relation > b.relation ? 1 : a.id < b.id ? -1 : a.id > b.id ? 1 : a.rev - b.rev || (a.hash < b.hash ? -1 : 1));
427
+ const overlaps: AssertionAnswerSet["overlaps"] = [];
428
+ if (t !== undefined && !query.history) {
429
+ const groups = new Map<string, AssertionItem[]>();
430
+ for (const found of items) if (found.answer === "yes" || found.answer === "unknown") {
431
+ const key = `${found.subject}\u0000${found.relation}`;
432
+ groups.set(key, [...(groups.get(key) ?? []), found]);
433
+ }
434
+ for (const group of groups.values()) {
435
+ if (new Set(group.map(found => found.value)).size < 2) continue;
436
+ const ids = [...new Set(group.map(found => found.id))];
437
+ if (ids.length < 2) continue;
438
+ overlaps.push({ subject: group[0]!.subject, relation: group[0]!.relation, ids, ...(group.some(found => found.answer === "unknown") ? { possible: true as const } : {}) });
439
+ }
440
+ }
441
+ const all = [...resolved.kept.values()];
442
+ return {
443
+ schemaVersion: 1, at: query.at ?? null, asOf,
444
+ pin: journal.segments.filter(s => s.tail).map(s => ({ segment: s.segment, seq: s.tail!.seq, hash: s.tail!.hash })),
445
+ coverage: {
446
+ journal: journal.present ? "present" : "absent",
447
+ beforeFirstEntry: !!asOf && all.length > 0 && kept.length === 0,
448
+ untrusted: [...journal.segments.filter(s => s.untrusted).map(s => ({ segment: s.segment, seq: s.untrusted!.seq, reason: s.untrusted!.reason })), ...resolved.untrusted],
449
+ unsupported: journal.segments.filter(s => s.unsupported).map(s => ({ segment: s.segment, seq: s.unsupported!.seq })),
450
+ tornTail: journal.segments.filter(s => s.tornTail).map(s => s.segment),
451
+ partialBatch: journal.segments.filter(s => s.partialBatch).map(s => ({ segment: s.segment, seq: s.partialBatch!.seq })),
452
+ purged,
453
+ },
454
+ items, overlaps,
455
+ };
456
+ }
457
+
458
+ // ---------------------------------------------------------------- write contract
459
+
460
+ export type AssertOp =
461
+ | { op: "declare"; subject: string; label?: string; note?: string }
462
+ | { op: "relink"; subject: string; note: string }
463
+ | { op: "assert"; subject: string; relation: string; value: string; kind: "state" | "event"; from?: string; to?: string; held_on?: string; on?: string; evidence?: EvidenceEntry[]; source?: string[] }
464
+ | { op: "revise"; id: string; expected_heads: string[]; value: string; kind: "state" | "event"; from?: string; to?: string; held_on?: string; on?: string; evidence?: EvidenceEntry[]; source?: string[] }
465
+ | { op: "retract"; id: string; expected_heads: string[]; reason: typeof REASONS[number] };
466
+ export interface AssertRequest { vault: string; ops: unknown; channel?: "cli" | "mcp"; dryRun?: boolean; log?: LogEvent }
467
+ export interface AssertReceipt {
468
+ ok: boolean; applied: boolean; dryRun: boolean;
469
+ segment: string | null; recordedAt?: string;
470
+ entries: { seq?: number; id: string; rev?: number; op: EntryOp; hash?: string }[];
471
+ /** Recovery and segment notes, for example a truncated torn tail or a new segment and why. */
472
+ recovery: string[];
473
+ issues: WriteIssue[];
474
+ indexUpdated: false;
475
+ log?: LogReceipt;
476
+ }
477
+ class Refused extends Error { constructor(readonly issues: WriteIssue[]) { super(issues[0]?.message ?? "refused"); } }
478
+ /** A refusal from a read-side helper; the MCP guard and receipts surface its code and message. */
479
+ export class Coded extends Error { constructor(readonly code: string, message: string) { super(message); } }
480
+ function coded(code: string, message: string): Error { return new Coded(code, message); }
481
+ const err = (code: string, message: string, path?: string): WriteIssue => ({ code, severity: "error", message, ...(path === undefined ? {} : { path }) });
482
+ function refuse(code: string, message: string, path?: string): never { throw new Refused([err(code, message, path)]); }
483
+
484
+ const OP_KEYS: Record<string, string[]> = {
485
+ declare: ["op", "subject", "label", "note"],
486
+ relink: ["op", "subject", "note"],
487
+ assert: ["op", "subject", "relation", "value", "kind", "from", "to", "held_on", "on", "evidence", "source"],
488
+ revise: ["op", "id", "expected_heads", "value", "kind", "from", "to", "held_on", "on", "evidence", "source"],
489
+ retract: ["op", "id", "expected_heads", "reason"],
490
+ };
491
+ const bytes = (text: string) => Buffer.byteLength(text);
492
+ /** Shape, bound and temporal checks of one op, returning the world-time payload fields. */
493
+ function temporal(op: Record<string, unknown>, at: string): Record<string, unknown> {
494
+ if (op.kind === "event") {
495
+ for (const key of ["from", "to", "held_on"]) if (op[key] !== undefined) refuse("V01", `${at}: an event takes on, not ${key}; move the date to on or use kind state`);
496
+ if (op.on === "unknown" || op.on === "open") refuse("V01", `${at}: on cannot be unknown or open; give the event's date at year, month or day precision`);
497
+ if (!dateRange(op.on)) refuse("V01", `${at}: on must be a date value YYYY, YYYY-MM or YYYY-MM-DD with year 0001..9999; write on as one of those`);
498
+ return { kind: "event", on: op.on };
499
+ }
500
+ if (op.kind !== "state") refuse("V01", `${at}: kind must be state or event; write kind: state with from and to, or kind: event with on`);
501
+ if (op.on !== undefined) refuse("V01", `${at}: a state takes from and to, not on; use kind event for a dated occurrence`);
502
+ if (op.from === undefined || op.to === undefined) refuse("V01", `${at}: a state needs both from and to; write to: open for no asserted end or to: unknown for an unknown end`);
503
+ const bounds = stateBounds(op.from, op.to, op.held_on);
504
+ if (typeof bounds === "string") refuse("V01", `${at}: ${bounds}`);
505
+ return { kind: "state", from: op.from, to: op.to, ...(op.held_on !== undefined ? { held_on: op.held_on } : {}) };
506
+ }
507
+ function value(op: Record<string, unknown>, at: string): string {
508
+ if (typeof op.value !== "string" || !op.value || bytes(op.value) > MAX_VALUE_BYTES || /\p{Cc}/u.test(op.value) || !op.value.isWellFormed()) refuse("V01", `${at}: value must be 1..${MAX_VALUE_BYTES} UTF-8 bytes of well-formed text without control characters; shorten it and remove control characters`);
509
+ return op.value;
510
+ }
511
+ interface Support { evidence: (EvidenceEntry & { status: "verified" | "unverified_external" })[]; source?: string[] }
512
+ /** Evidence per entry with `verifyEvidenceEntry`, source references, and owner decision O2 (at least one of either). */
513
+ function support(op: Record<string, unknown>, at: string, vault: VaultSpec, config: VmemConfig, reads: EvidenceReads): Support {
514
+ const out: Support = { evidence: [] };
515
+ if (op.source !== undefined) {
516
+ if (!Array.isArray(op.source)) refuse("V01", `${at}: source must be a list of 1..32 source references; send an array of workspace paths, URLs or mem: ids`);
517
+ let refs: ReturnType<typeof sourceReferences>;
518
+ try { refs = sourceReferences(op.source); } catch (caught) { refuse("V01", `${at}: ${(caught as Error).message}`); }
519
+ // A path reference is denied by its own value or by the workspace path it resolves to, as `src/analysis-input.ts` reads it.
520
+ const root = sourceWorkspaceRoot(vault), denyPaths = config.denyPaths ?? [];
521
+ const denied = (ref: (typeof refs)[number]) => ref.kind === "path" && (isDenied(ref.value, denyPaths) || (root !== undefined && isDenied(canonicalPath(resolve(root, ref.value)), denyPaths)));
522
+ for (const ref of refs) if (denied(ref)) refuse("V06", `${at}: source ${ref.value} is denied by current policy; cite another source`);
523
+ out.source = refs.map(ref => ref.value);
524
+ }
525
+ if (op.evidence !== undefined) {
526
+ const list = op.evidence;
527
+ if (Array.isArray(list) && list.some(entry => !entry || typeof entry !== "object" || typeof (entry as Record<string, unknown>).source !== "string"))
528
+ refuse("V01", `${at}: each evidence entry needs source, sha256 and quote (issue 233 version 1 shape); copy the entry shape from vmem evidence output`);
529
+ const sources = Array.isArray(list) ? list.map(entry => (entry as { source: string }).source) : [];
530
+ const parsed = parseEvidence(list, sources.length ? sources : undefined);
531
+ if (parsed.problem) refuse("V01", `${at}: ${parsed.problem}`);
532
+ for (const [index, entry] of parsed.entries.entries()) {
533
+ if ("problem" in entry) refuse("V01", `${at}.evidence[${index}]: ${entry.problem}`);
534
+ const result = verifyEvidenceEntry(vault, entry, index, config.denyPaths ?? [], reads);
535
+ if (result.reason === "denied") refuse("V06", `${at}.evidence[${index}]: source is denied by current policy; cite another source`);
536
+ if (result.status === "unverified_external") { out.evidence.push({ ...entry, status: "unverified_external" }); continue; }
537
+ if (result.status !== "verified") {
538
+ const next = result.reason === "unresolved_source_root" ? "register the vault with --registry so its workspace root resolves, or cite the source as an external reference (URL or mem: id)"
539
+ : result.reason === "outside_vault" ? "cite a flat notes/*.md of this vault by its workspace-relative path, for example vault/notes/x.md"
540
+ : "re-read the source and copy the quote and its current sha256 exactly";
541
+ refuse("EVIDENCE", `${at}.evidence[${index}]: ${result.status}${result.reason ? ` (${result.reason})` : ""}; ${next}`);
542
+ }
543
+ out.evidence.push({ ...entry, status: "verified" });
544
+ }
545
+ }
546
+ if (!out.evidence.length && !out.source?.length) refuse("V01", `${at}: an assertion needs at least one evidence entry or source reference (owner decision O2); add evidence or source`);
547
+ return out;
548
+ }
549
+
550
+ interface Planned { op: EntryOp; payload: Record<string, unknown>; parents?: string[]; id: string; target?: string }
551
+ interface Context { vault: VaultSpec; config: VmemConfig; root: string; channel: "cli" | "mcp" }
552
+ function context(home: string, request: { vault: string; channel?: "cli" | "mcp" }, verb = "assertion appends"): Context {
553
+ const config = loadRegistry(home), vault = config.vaults.find(item => item.id === request.vault);
554
+ if (!vault) refuse("V04", "unknown vault id; list registered vaults with vmem status");
555
+ const channel = request.channel ?? "cli";
556
+ if (channel !== "cli" && channel !== "mcp") refuse("POLICY", "unknown write channel; use cli or mcp");
557
+ if (vault.write === "none" || (channel === "mcp" && vault.write !== "mcp")) refuse("POLICY", `vault write policy (${vault.write}) refuses ${verb} over ${channel}; change the policy with vmem vaults add or use an allowed channel`);
558
+ const unenforceable = unenforceablePii(vault);
559
+ if (unenforceable) refuse("PII_POLICY", unenforceable);
560
+ let root: string;
561
+ try { root = realpathSync(vault.path); } catch { refuse("V04", "registered vault path is missing; restore it or re-register the vault"); }
562
+ if (root !== vault.path || !lstatSync(root).isDirectory()) refuse("V04", "registered vault path changed or is not a plain directory; re-register the vault");
563
+ if (isDenied(canonicalPath(join(root, ASSERTIONS_DIR)), config.denyPaths ?? [])) refuse("V06", "the assertions/ path is denied by denyPaths; remove the deny entry to record assertions in this vault");
564
+ return { vault, config, root, channel };
565
+ }
566
+ /** Validate a batch against the journal as read (shapes, bounds, temporal rules, evidence, screening, heads). */
567
+ function plan(ctx: Context, ops: unknown, journal: VerifiedJournal): Planned[] {
568
+ if (!ops || !Array.isArray(ops) || ops.length < 1 || ops.length > MAX_BATCH_OPS) refuse("V01", `ops must be a list of 1..${MAX_BATCH_OPS} operations; split larger batches`);
569
+ if (bytes(canonical(ops)) > MAX_BATCH_BYTES) refuse("V09", `the canonical batch exceeds ${MAX_BATCH_BYTES} bytes; split it into smaller batches`);
570
+ const resolved = resolveEntries(journal), { assertions, subjects } = states(resolved.kept.values());
571
+ const declared = new Set(subjects.keys()), touched = new Set<string>(), reads: EvidenceReads = new Map(), planned: Planned[] = [];
572
+ const labels = new Map([...subjects].map(([subject, current]) => [subject, current.entry.payload?.label]));
573
+ for (const [index, raw] of ops.entries()) {
574
+ const at = `ops[${index}]`;
575
+ if (!raw || typeof raw !== "object" || Array.isArray(raw)) refuse("V01", `${at}: expected an object with op; send {op: declare|relink|assert|revise|retract, ...}`);
576
+ const op = raw as Record<string, unknown>, keys = OP_KEYS[op.op as string];
577
+ if (!keys) refuse("V01", `${at}: op must be declare, relink, assert, revise or retract; correct the op name`);
578
+ for (const key of Object.keys(op)) if (!keys.includes(key)) refuse("V01", `${at}: unknown field ${key.slice(0, 32)} for ${String(op.op)}; vmem assigns ids, times and hashes itself`);
579
+ let entry: Planned;
580
+ if (op.op === "declare" || op.op === "relink") {
581
+ if (typeof op.subject !== "string" || !SUBJECT.test(op.subject)) refuse("V01", `${at}: subject must match s:[a-z0-9][a-z0-9-]{0,63}; write s: then lowercase letters, digits and hyphens`);
582
+ if (op.op === "declare" && declared.has(op.subject)) refuse("V01", `${at}: subject ${op.subject} is already declared; use relink to change its note`);
583
+ if (op.op === "relink" && !declared.has(op.subject)) refuse("V01", `${at}: subject ${op.subject} is not declared; declare it before relinking`);
584
+ if (op.op === "relink" && op.note === undefined) refuse("V01", `${at}: relink needs a note path; supply notes/<stem>.md`);
585
+ if (op.label !== undefined && (typeof op.label !== "string" || !op.label.trim() || [...op.label].length > MAX_LABEL_CHARS || /\p{Cc}/u.test(op.label) || !op.label.isWellFormed())) refuse("V01", `${at}: label must be 1..${MAX_LABEL_CHARS} characters without control characters; shorten it and remove control characters`);
586
+ if (op.note !== undefined && (typeof op.note !== "string" || !/^notes\/[^/\\]+\.md$/.test(op.note) || /\p{Cc}/u.test(op.note))) refuse("V01", `${at}: note must be a flat notes/<stem>.md path of this vault; cite this vault's note by its notes/<stem>.md path`);
587
+ declared.add(op.subject);
588
+ const label = op.op === "relink" ? labels.get(op.subject) : op.label;
589
+ labels.set(op.subject, label);
590
+ entry = { op: "subject", id: op.subject, payload: { subject: op.subject, ...(label !== undefined ? { label } : {}), ...(op.note !== undefined ? { note: op.note } : {}) } };
591
+ } else if (op.op === "assert") {
592
+ if (typeof op.subject !== "string" || !declared.has(op.subject)) refuse("V01", `${at}: subject ${String(op.subject).slice(0, 80)} is not declared; add a declare op earlier in this batch`);
593
+ if (typeof op.relation !== "string" || !RELATION.test(op.relation)) refuse("V01", `${at}: relation must match [a-z0-9][a-z0-9-]{0,63}; write lowercase letters, digits and hyphens`);
594
+ const world = temporal(op, at), held = value(op, at), backing = support(op, at, ctx.vault, ctx.config, reads);
595
+ entry = { op: "assert", id: "", payload: { rev: 1, subject: op.subject, relation: op.relation, value: held, ...world, evidence: backing.evidence, ...(backing.source ? { source: backing.source } : {}) } };
596
+ } else {
597
+ if (typeof op.id !== "string" || !ASSERTION_ID.test(op.id)) refuse("V01", `${at}: id must be an assertion id a:<segment>:<seq> as returned by a receipt`);
598
+ const state = assertions.get(op.id);
599
+ if (!state) refuse("V01", `${at}: assertion ${op.id} is not in the verified journal; check the id, or sync the segment that holds it`);
600
+ if (touched.has(op.id)) refuse("V01", `${at}: ${op.id} appears twice in this batch; send the second change in a later batch with the new head`);
601
+ if (state.purged) refuse("V01", `${at}: ${op.id} is purged; assert a new id instead`);
602
+ if (state.retracted) refuse("V01", `${at}: ${op.id} is retracted; assert a new id instead`);
603
+ const heads = state.heads.map(head => head.entry.hash).sort(), expected = op.expected_heads;
604
+ if (!Array.isArray(expected) || !expected.length || expected.length > 32 || expected.some(h => typeof h !== "string" || !HEX64.test(h))) refuse("V01", `${at}: expected_heads must list the hashes of the assertion's current heads; re-read the assertion and send every head hash`);
605
+ const given = [...new Set(expected as string[])].sort();
606
+ if (given.length !== heads.length || given.some((h, i) => h !== heads[i])) refuse("STALE_HEADS", `${at}: expected_heads does not equal the current head set of ${op.id} (${heads.join(", ")}); re-read the assertion and resend with every head`);
607
+ touched.add(op.id);
608
+ const rev = Math.max(...state.heads.map(head => head.entry.op === "assert" ? 1 : Number(head.entry.payload?.rev ?? 1))) + 1;
609
+ if (op.op === "retract") {
610
+ if (!REASONS.includes(op.reason as typeof REASONS[number])) refuse("V01", `${at}: reason must be ${REASONS.join(", ")}; pick one of those reasons`);
611
+ entry = { op: "retract", id: op.id, target: op.id, parents: heads, payload: { id: op.id, rev, reason: op.reason } };
612
+ } else {
613
+ const world = temporal(op, at), held = value(op, at), backing = support(op, at, ctx.vault, ctx.config, reads);
614
+ entry = { op: "revise", id: op.id, target: op.id, parents: heads, payload: { id: op.id, rev, value: held, ...world, evidence: backing.evidence, ...(backing.source ? { source: backing.source } : {}) } };
615
+ }
616
+ }
617
+ const text = canonical(entry.payload);
618
+ if (bytes(text) > MAX_PAYLOAD_BYTES) refuse("V09", `${at}: payload exceeds ${MAX_PAYLOAD_BYTES} bytes as canonical JSON; shorten quotes or split evidence`);
619
+ const screened = [...screenContent(text, ctx.vault, ctx.config, "notes"), ...screenMetadata(entry.payload, { vault: ctx.vault, config: ctx.config, piiSurface: "notes" }, at)]
620
+ .filter(found => found.severity === "error");
621
+ if (screened.length) throw new Refused(screened.map(found => ({ ...found, path: at, message: `${at}: ${found.message}; remove the secret or personal data, or cite it by reference` })));
622
+ planned.push(entry);
623
+ }
624
+ return planned;
625
+ }
626
+ /** CLOCK (design: Write contract): no time before the segment tail or before any parent's effective record time. */
627
+ function clockCheck(planned: Planned[], journal: VerifiedJournal, tailTime: string | undefined, recordedAt: string): void {
628
+ if (tailTime && recordedAt < tailTime) refuse("CLOCK", `the writer clock (${recordedAt}) is before the segment's last entry (${tailTime}); wait until after ${tailTime} or correct the system clock`);
629
+ const resolved = resolveEntries(journal);
630
+ for (const entry of planned) for (const parent of entry.parents ?? []) {
631
+ const kept = resolved.kept.get(parent);
632
+ if (kept && recordedAt < kept.effective) refuse("CLOCK", `the writer clock (${recordedAt}) is before parent ${parent.slice(0, 12)} of ${entry.id} (recorded ${kept.effective}); wait until after ${kept.effective} or correct the system clock`);
633
+ }
634
+ }
635
+ interface WriterRecord { segment: string; seq: number; hash: string }
636
+ const writerFile = (home: string, vault: string) => join(home, "assertion-writers", `${vault}.json`);
637
+ function loadWriter(home: string, vault: string): WriterRecord | undefined {
638
+ try {
639
+ const data = readBounded(writerFile(home, vault), 4096);
640
+ if (typeof data === "string") return undefined;
641
+ const parsed = JSON.parse(data.toString("utf8")) as Record<string, unknown>;
642
+ return typeof parsed.segment === "string" && SEGMENT.test(parsed.segment) && Number.isSafeInteger(parsed.seq) && typeof parsed.hash === "string" && HEX64.test(parsed.hash)
643
+ ? { segment: parsed.segment, seq: parsed.seq as number, hash: parsed.hash } : undefined;
644
+ } catch { return undefined; }
645
+ }
646
+ function saveWriter(home: string, vault: string, record: WriterRecord): void {
647
+ const dir = join(home, "assertion-writers");
648
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
649
+ const temporary = join(dir, `.${vault}-${randomBytes(6).toString("hex")}.tmp`);
650
+ const fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
651
+ try { writeFileSync(fd, JSON.stringify(record) + "\n"); fsyncSync(fd); } finally { closeSync(fd); }
652
+ renameSync(temporary, writerFile(home, vault));
653
+ syncDirectory(dir);
654
+ }
655
+ /** Choose the segment for the next batch: the clone's own healthy segment, or a new one and why. */
656
+ function chooseSegment(home: string, vaultId: string, journal: VerifiedJournal, batchBytes: number): { segment: string; report?: SegmentReport; fresh: boolean; note?: string } {
657
+ const record = loadWriter(home, vaultId), fresh = (note?: string) => ({ segment: randomBytes(8).toString("hex"), fresh: true, ...(note ? { note } : {}) });
658
+ if (!record) return fresh();
659
+ const report = journal.segments.find(s => s.segment === record.segment);
660
+ if (!report) return fresh(`segment ${record.segment} named by the writer record is missing; started a new segment`);
661
+ if (report.untrusted || report.unsupported) return fresh(`segment ${record.segment} fails verification from seq ${(report.untrusted ?? report.unsupported)!.seq}; started a new segment (restore the file from Git to read its later entries)`);
662
+ const at = report.entries[record.seq - 1];
663
+ if (!at || at.hash !== record.hash) return fresh(`segment ${record.segment} is shorter than or differs from the writer record (seq ${record.seq}); truncation detected, started a new segment`);
664
+ if (report.verifiedBytes + batchBytes > MAX_SEGMENT_BYTES) return fresh(`segment ${record.segment} reached ${MAX_SEGMENT_BYTES} bytes; started a new segment`);
665
+ return { segment: record.segment, report, fresh: false };
666
+ }
667
+ function actorOf(channel: "cli" | "mcp", env: NodeJS.ProcessEnv): "person" | "agent" {
668
+ return channel === "mcp" || AGENT_MARKERS.some(marker => typeof env[marker] === "string" && env[marker]!.length > 0) ? "agent" : "person";
669
+ }
670
+ /** Take `assertions.lock`. Only EEXIST means another writer; any other open failure names its own cause. */
671
+ function acquire(root: string): { fd: number; file: string; ino: number; dev: number } {
672
+ const file = join(root, ASSERTIONS_LOCK), deadline = Date.now() + 2000, sleeper = new Int32Array(new SharedArrayBuffer(4));
673
+ for (;;) {
674
+ let fd: number;
675
+ try { fd = openSync(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); }
676
+ catch (caught) {
677
+ const code = (caught as NodeJS.ErrnoException).code ?? "unknown error";
678
+ if (code !== "EEXIST") refuse("LOCK", `${ASSERTIONS_LOCK} cannot be created in the vault root (${code}); fix the vault directory's permission, ownership or read-only mount, then retry`);
679
+ if (Date.now() < deadline) { Atomics.wait(sleeper, 0, 0, 5); continue; }
680
+ refuse("LOCKED", `${ASSERTIONS_LOCK} is held by another writer; retry shortly, or remove the lock file only after confirming no vmem process is appending`);
681
+ }
682
+ let stat;
683
+ try { stat = fstatSync(fd); writeFileSync(fd, JSON.stringify({ pid: process.pid, host: hostname(), created: new Date().toISOString() }) + "\n"); }
684
+ catch (caught) {
685
+ // A half-created lock is removed by identity so later appends do not read it as another writer.
686
+ const code = (caught as NodeJS.ErrnoException).code ?? "unknown error";
687
+ try { closeSync(fd); } catch { /* the refusal below is the signal */ }
688
+ try { const owned = lstatSync(file); if (Number(owned.ino) === Number(stat?.ino ?? -1) && Number(owned.dev) === Number(stat?.dev ?? -1)) unlinkSync(file); }
689
+ catch { /* the refusal below is the signal */ }
690
+ refuse("LOCK", `the ${ASSERTIONS_LOCK} record could not be written (${code}); check free space and permissions in the vault root, then retry`);
691
+ }
692
+ return { fd, file, ino: Number(stat.ino), dev: Number(stat.dev) };
693
+ }
694
+ }
695
+ function release(lock: { fd: number; file: string; ino: number; dev: number }, issues: WriteIssue[]): void {
696
+ try { closeSync(lock.fd); } catch { issues.push({ code: "CLEANUP", severity: "warning", message: "assertions lock descriptor close failed" }); }
697
+ try {
698
+ const stat = lstatSync(lock.file);
699
+ if (stat.isSymbolicLink() || Number(stat.ino) !== lock.ino || Number(stat.dev) !== lock.dev) issues.push({ code: "CLEANUP", severity: "warning", message: "assertions lock ownership changed; retained it, inspect before removing" });
700
+ else unlinkSync(lock.file);
701
+ } catch { issues.push({ code: "CLEANUP", severity: "warning", message: "assertions lock retained; inspect before removing it manually" }); }
702
+ }
703
+
704
+ /**
705
+ * Validate and append one batch (design: Write contract). All-or-nothing: any error refuses the whole batch before
706
+ * any byte is written. A dry run validates against the journal as read, without lock, append or `recordedAt`.
707
+ */
708
+ export function appendAssertions(home: string, request: AssertRequest, options: { env?: NodeJS.ProcessEnv; now?: Date } = {}): AssertReceipt {
709
+ return appendAssertionsInternal(home, request, options);
710
+ }
711
+ function appendAssertionsInternal(home: string, request: AssertRequest, options: { env?: NodeJS.ProcessEnv; now?: Date }, heldRoot?: string): AssertReceipt {
712
+ const env = options.env ?? process.env;
713
+ const receipt: AssertReceipt = { ok: false, applied: false, dryRun: request?.dryRun === true, segment: null, entries: [], recovery: [], issues: [], indexUpdated: false };
714
+ let lock: ReturnType<typeof acquire> | undefined;
715
+ try {
716
+ if (!request || typeof request !== "object" || Object.keys(request).some(key => !["vault", "ops", "channel", "dryRun", "log"].includes(key))) refuse("V01", "unknown request option; send {vault, ops[, dryRun, log]}");
717
+ if (request.dryRun !== undefined && typeof request.dryRun !== "boolean") refuse("V01", "dryRun must be a boolean");
718
+ const ctx = context(home, request);
719
+ if (heldRoot && ctx.root !== heldRoot) refuse("V04", "registered vault root changed during relink; inspect the vault and retry the relink");
720
+ if (request.log !== undefined) {
721
+ const logIssues = checkLogEvent(home, { vault: request.vault, event: request.log, channel: ctx.channel }, env);
722
+ if (logIssues.length) throw new Refused(logIssues.map(found => ({ ...found, message: `log event refused, nothing written: ${found.message}; fix the event fields (rules as for log append) or omit it` })));
723
+ }
724
+ if (receipt.dryRun) {
725
+ const journal = readJournal(ctx.root, ctx.config.denyPaths ?? []);
726
+ const planned = plan(ctx, request.ops, journal);
727
+ receipt.entries = planned.map(entry => ({ id: entry.id || "(assigned at append)", op: entry.op, ...(entry.op !== "subject" ? { rev: Number(entry.payload.rev) } : {}) }));
728
+ receipt.ok = true;
729
+ return receipt;
730
+ }
731
+ if (!heldRoot) lock = acquire(ctx.root);
732
+ const journal = readJournal(ctx.root, ctx.config.denyPaths ?? []);
733
+ const planned = plan(ctx, request.ops, journal);
734
+ if (journal.entries + planned.length > MAX_JOURNAL_ENTRIES) refuse("V09", `the journal would exceed ${MAX_JOURNAL_ENTRIES} entries; appends refuse rather than rotate history`);
735
+ // An over-estimate only, so a segment chosen on it has room for the real lines; `parents` cost their own bytes.
736
+ const estimate = planned.reduce((sum, entry) => sum + bytes(canonical(entry.payload)) + 1024 + (entry.parents ?? []).reduce((cost, parent) => cost + parent.length + 4, 0), 0);
737
+ if (journal.bytes + estimate > MAX_JOURNAL_BYTES) refuse("V09", `the journal would exceed ${MAX_JOURNAL_BYTES} bytes; appends refuse rather than rotate history`);
738
+ const chosen = chooseSegment(home, ctx.vault.id, journal, estimate);
739
+ if (chosen.note) receipt.recovery.push(chosen.note);
740
+ const recordedAt = instant(options.now ?? new Date());
741
+ clockCheck(planned, journal, chosen.report?.tail?.recordedAt, recordedAt);
742
+ const currentSubjects = states(resolveEntries(journal).kept.values()).subjects;
743
+ for (const entry of planned) if (entry.op === "subject") {
744
+ const current = currentSubjects.get(entry.id);
745
+ if (current && (recordedAt < current.effective || (recordedAt === current.effective && chosen.segment < current.entry.seg)))
746
+ refuse("CLOCK", `the writer clock cannot place the relink after the current subject entry (${current.effective}); wait until the next second or correct the system clock and retry`);
747
+ }
748
+ // Lines: assert ids name the seq of their own entry in the chosen segment.
749
+ const actor = actorOf(ctx.channel, env), base = chosen.report?.entries.length ?? 0, batchId = `${chosen.segment}:${base + 1}`;
750
+ let prev = chosen.report?.tail?.hash ?? ZERO;
751
+ const lines: string[] = [];
752
+ for (const [index, entry] of planned.entries()) {
753
+ const seq = base + index + 1;
754
+ if (entry.op === "assert") entry.id = `a:${chosen.segment}:${seq}`;
755
+ const payload = entry.op === "assert" ? { id: entry.id, ...entry.payload } : entry.payload;
756
+ const draft = { v: ASSERTION_SCHEMA_VERSION, seg: chosen.segment, seq, prev, recorded_at: recordedAt, channel: ctx.channel, actor, op: entry.op,
757
+ batch: { id: batchId, size: planned.length, index }, ...(entry.parents ? { parents: entry.parents } : {}), payload_sha256: payloadHash(payload), payload };
758
+ const hash = entryHash(draft as Omit<JournalEntry, "hash">), line = canonical({ ...draft, hash });
759
+ lines.push(line + "\n"); prev = hash;
760
+ receipt.entries.push({ seq, id: entry.id, op: entry.op, hash, ...(entry.op !== "subject" ? { rev: Number(entry.payload.rev) } : {}) });
761
+ }
762
+ const buffer = Buffer.from(lines.join(""));
763
+ // The journal bound is checked on the bytes that will be written, before the file is opened.
764
+ if (journal.bytes + buffer.length > MAX_JOURNAL_BYTES) refuse("V09", `the journal would exceed ${MAX_JOURNAL_BYTES} bytes once this batch is written; appends refuse rather than rotate history`);
765
+ const dir = join(ctx.root, ASSERTIONS_DIR);
766
+ let createdDir = false;
767
+ try { const stat = lstatSync(dir); if (stat.isSymbolicLink() || !stat.isDirectory()) refuse("V04", "assertions/ must be a plain directory; move the file or link aside"); }
768
+ catch (caught) { if ((caught as NodeJS.ErrnoException).code !== "ENOENT") throw caught; mkdirSync(dir, { mode: 0o755 }); createdDir = true; }
769
+ const file = join(dir, `${chosen.segment}.jsonl`);
770
+ let fd: number;
771
+ try { fd = openSync(file, constants.O_RDWR | constants.O_APPEND | constants.O_CREAT | (chosen.fresh ? constants.O_EXCL : 0) | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o644); }
772
+ catch (caught) {
773
+ if ((caught as NodeJS.ErrnoException).code === "ELOOP") refuse("V04", `${ASSERTIONS_DIR}/${chosen.segment}.jsonl is a symbolic link; restore the segment from Git or move the link aside, then retry`);
774
+ throw caught;
775
+ }
776
+ try {
777
+ const before = fstatSync(fd);
778
+ if (!before.isFile() || before.nlink !== 1) refuse("V04", "the segment must be a plain nonlinked file; restore it from Git");
779
+ // Forward recovery on the clone's own segment: drop a torn tail or partial batch after the verified prefix.
780
+ if (chosen.report && before.size !== chosen.report.verifiedBytes) {
781
+ if (before.size < chosen.report.verifiedBytes) refuse("CONCURRENT", "the segment shrank while it was read; retry the batch");
782
+ const dropped = before.size - chosen.report.verifiedBytes;
783
+ ftruncateSync(fd, chosen.report.verifiedBytes); fsyncSync(fd);
784
+ receipt.recovery.push(`truncated ${dropped} bytes after seq ${chosen.report.tail?.seq ?? 0} of segment ${chosen.segment} (${chosen.report.partialBatch ? "partial batch" : "torn tail"})`);
785
+ }
786
+ const start = chosen.report?.verifiedBytes ?? 0;
787
+ /** Undo the batch bytes after a failed write or fsync; true when the segment is back at its verified prefix. */
788
+ const rollback = () => { try { ftruncateSync(fd, start); fsyncSync(fd); return true; } catch { return false; } };
789
+ const unpublished = (code: string, message: string): never => {
790
+ receipt.applied = false; receipt.segment = null; delete receipt.recordedAt; receipt.entries = [];
791
+ refuse(code, message);
792
+ };
793
+ let written = 0;
794
+ try { written = writeSync(fd, buffer, 0, buffer.length, null); }
795
+ catch {
796
+ const after = fstatSync(fd);
797
+ if (after.size > start && !rollback()) refuse("DURABILITY", "the batch write failed and the segment could not be truncated back; inspect the segment before retrying");
798
+ unpublished("WRITE", "the batch write failed and was truncated back; nothing was appended. Check disk space and retry");
799
+ }
800
+ if (written !== buffer.length) {
801
+ if (!rollback()) refuse("DURABILITY", `short batch write (${written} of ${buffer.length} bytes) left in the segment and it could not be truncated back; inspect it before retrying`);
802
+ unpublished("WRITE", "short batch write truncated back; nothing was appended. Check disk space and retry");
803
+ }
804
+ // The batch bytes are in the segment from here on: report them, so a later failure never invites a replay that
805
+ // would duplicate the assertions.
806
+ receipt.applied = true; receipt.segment = chosen.segment; receipt.recordedAt = recordedAt;
807
+ try { fsyncSync(fd); }
808
+ catch {
809
+ if (rollback()) unpublished("WRITE", "the batch fsync failed and the batch was truncated back; nothing was appended. Check disk space and retry");
810
+ refuse("DURABILITY", `fsync of segment ${chosen.segment} failed after the batch was written; its ${receipt.entries.length} entries may not survive a crash. Inspect the segment and the writer record before appending again`);
811
+ }
812
+ } finally { closeSync(fd); }
813
+ if (chosen.fresh) syncDirectory(dir);
814
+ if (createdDir) syncDirectory(ctx.root);
815
+ receipt.segment = chosen.segment; receipt.recordedAt = recordedAt;
816
+ const last = receipt.entries.at(-1)!;
817
+ try { saveWriter(home, ctx.vault.id, { segment: chosen.segment, seq: last.seq!, hash: last.hash! }); }
818
+ catch { receipt.issues.push({ code: "WRITER_RECORD", severity: "warning", message: "the batch is appended but the writer record was not updated; the next append starts a new segment" }); }
819
+ receipt.ok = true;
820
+ } catch (caught) {
821
+ if (caught instanceof Refused) receipt.issues.push(...caught.issues);
822
+ else if (caught instanceof Coded) receipt.issues.push(err(caught.code, caught.message));
823
+ // Once the batch bytes are in the segment, a later failure keeps `applied` and never advises a replay.
824
+ else if (receipt.applied) receipt.issues.push(err("DURABILITY", `the batch is in segment ${receipt.segment} but a later step failed (${(caught as NodeJS.ErrnoException).code ?? (caught as Error).message}); inspect the segment and the writer record before appending again`));
825
+ else receipt.issues.push(err("IO", "assertion append failed on file I/O; check permissions and disk space, then retry"));
826
+ receipt.ok = false;
827
+ } finally {
828
+ if (lock) release(lock, receipt.issues);
829
+ }
830
+ if (receipt.applied && request.log !== undefined) {
831
+ receipt.log = appendLog(home, { vault: request.vault, event: request.log, channel: request.channel ?? "cli" }, { env });
832
+ }
833
+ return receipt;
834
+ }
835
+
836
+ /** Relink current subjects under one assertion lock, after the caller has published the note write. */
837
+ export function relinkSubjects(home: string, request: { vault: string; from: string; to: string; channel: "cli" | "mcp"; planned: string[] }, options: { env?: NodeJS.ProcessEnv; now?: Date } = {}): { relinked: string[]; issue?: WriteIssue } {
838
+ const relinked: string[] = [], issues: WriteIssue[] = [];
839
+ let pending = [...request.planned], uncertain: string[] = [], lock: ReturnType<typeof acquire> | undefined;
840
+ try {
841
+ const ctx = context(home, request, "automatic subject relinking");
842
+ try { lstatSync(join(ctx.root, ASSERTIONS_DIR)); } catch (error) {
843
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") return { relinked };
844
+ throw error;
845
+ }
846
+ lock = acquire(ctx.root);
847
+ const locked = context(home, request, "automatic subject relinking");
848
+ if (locked.root !== ctx.root) throw new Error("registered vault root changed while acquiring the assertion lock");
849
+ pending = subjectsAtNote(readJournal(locked.root, locked.config.denyPaths ?? []), request.from);
850
+ while (pending.length) {
851
+ const batch = pending.slice(0, MAX_BATCH_OPS);
852
+ const receipt = appendAssertionsInternal(home, { vault: request.vault, channel: request.channel, ops: batch.map(subject => ({ op: "relink", subject, note: request.to })) }, options, ctx.root);
853
+ if (receipt.applied) { relinked.push(...batch); pending = pending.slice(batch.length); }
854
+ if (!receipt.ok) { if (receipt.applied) uncertain = batch; throw new Error(receipt.issues.map(issue => issue.message).join("; ") || "assertion append refused"); }
855
+ if (!receipt.applied) throw new Error("assertion append did not publish");
856
+ }
857
+ } catch (error) {
858
+ const cause = error instanceof Refused ? error.issues.map(issue => issue.message).join("; ") : error instanceof Error ? error.message : "assertion append failed";
859
+ const commands = (pending.length ? pending : uncertain).slice(0, MAX_BATCH_OPS).map(subject => ({ op: "relink", subject, note: request.to }));
860
+ const command = commands.length ? `printf '%s\\n' ${shellWord(JSON.stringify({ ops: commands }))} | vmem assert ${shellWord(request.vault)} --batch -` : `vmem assert ${shellWord(request.vault)} --batch -`;
861
+ issues.push({ code: "ASSERTIONS", severity: "warning", message: `note published but automatic relink failed (${cause}); ${uncertain.length ? "inspect the journal and run only for subjects still unlinked:" : commands.length ? "run" : "inspect the journal, supply relink operations on stdin, then run"} ${command}${pending.length > MAX_BATCH_OPS ? " and repeat for the remaining subjects" : ""}` });
862
+ } finally { if (lock) release(lock, issues); }
863
+ return { relinked, ...(issues.length ? { issue: issues[0] } : {}) };
864
+ }
865
+
866
+ // ---------------------------------------------------------------- purge (design: Retention and deletion, T12)
867
+
868
+ export const PURGE_LIST_LIMIT = 100;
869
+ export interface PurgeRequest { vault: string; id: string; reason: string; confirm?: boolean; fingerprint?: string; channel?: "cli" | "mcp" }
870
+ export interface PurgeReceipt {
871
+ ok: boolean; applied: boolean; preview: boolean; vault: string; assertion: string; reason: string;
872
+ /** Recorded in every `purged` marker this purge writes; absent from a preview. */
873
+ at?: string; fingerprint: string;
874
+ entries: { segment: string; seq: number; op: EntryOp; hash: string }[];
875
+ segments: { segment: string; entries: number; bytes: number; after: number }[];
876
+ /** Entries that already carried a purge marker and were left as they are. */
877
+ alreadyPurged: number; omitted: number;
878
+ recovery: string[];
879
+ issues: WriteIssue[];
880
+ }
881
+ const PURGE_KEYS = ["vault", "id", "reason", "confirm", "fingerprint", "channel"];
882
+
883
+ /** Every verified entry of one assertion, resolved through `parents` so a purged revision keeps its identity. */
884
+ function assertionEntries(journal: VerifiedJournal, id: string): JournalEntry[] {
885
+ const { kept } = resolveEntries(journal);
886
+ return [...kept.values()].filter(item => item.assertionId === id).map(item => item.entry)
887
+ .sort((a, b) => a.seg < b.seg ? -1 : a.seg > b.seg ? 1 : a.seq - b.seq);
888
+ }
889
+ /**
890
+ * The value a preview hands to confirm: the assertion, the reason, every entry hash and each affected segment's
891
+ * verified length and chain tail. `at` is left out because confirm assigns it, and the rewrite itself is derived
892
+ * from these bytes, so a segment that changed cannot pass with an old fingerprint.
893
+ */
894
+ function purgeFingerprint(root: string, id: string, reason: string, entries: readonly JournalEntry[], journal: VerifiedJournal): string {
895
+ const segments = [...new Set(entries.map(entry => entry.seg))].sort().map(segment => {
896
+ const report = journal.segments.find(value => value.segment === segment);
897
+ return [segment, report?.verifiedBytes ?? 0, report?.tail?.hash ?? ZERO];
898
+ });
899
+ return sha256(canonical({ purge: 1, root, assertion: id, reason, entries: entries.map(entry => entry.hash).sort(), segments }));
900
+ }
901
+
902
+ /**
903
+ * Remove an assertion's payloads in two steps (design: Retention and deletion). A preview changes nothing and
904
+ * returns a fingerprint; confirm rewrites each affected segment through a sibling file and a rename under
905
+ * `assertions.lock`, drops `payload`, keeps `payload_sha256` and every hashed field, and adds `purged`.
906
+ */
907
+ export function purgeAssertions(home: string, request: PurgeRequest, options: { env?: NodeJS.ProcessEnv; now?: Date } = {}): PurgeReceipt {
908
+ const receipt: PurgeReceipt = { ok: false, applied: false, preview: request?.confirm !== true, vault: String(request?.vault ?? ""), assertion: String(request?.id ?? ""), reason: String(request?.reason ?? ""), fingerprint: "", entries: [], segments: [], alreadyPurged: 0, omitted: 0, recovery: [], issues: [] };
909
+ let lock: ReturnType<typeof acquire> | undefined;
910
+ try {
911
+ if (!request || typeof request !== "object" || Array.isArray(request) || Object.keys(request).some(key => !PURGE_KEYS.includes(key))) refuse("V01", "unknown purge option; send {vault, id, reason[, confirm, fingerprint]}");
912
+ if (request.confirm !== undefined && typeof request.confirm !== "boolean") refuse("V01", "confirm must be a boolean; omit it for a preview");
913
+ if (request.confirm === true && typeof request.fingerprint !== "string") refuse("V01", `confirm needs the fingerprint the preview returned; rerun the preview and pass --fingerprint`);
914
+ if (request.confirm !== true && request.fingerprint !== undefined) refuse("V01", "a fingerprint is only used with confirm; drop it for a preview");
915
+ if (request.fingerprint !== undefined && !HEX64.test(request.fingerprint)) refuse("V01", "fingerprint must be the 64-character value a preview returned; rerun the preview");
916
+ const reason = request.reason;
917
+ // Same rule as `purgeShape`: UTF-16 units, so a reason this accepts is a reason verification accepts.
918
+ if (typeof reason !== "string" || !reason.trim() || reason.length > MAX_PURGE_REASON || /\p{Cc}/u.test(reason) || !reason.isWellFormed())
919
+ refuse("V01", `reason must be 1..${MAX_PURGE_REASON} characters of well-formed text without control characters; it stays in the journal, so keep it free of sensitive content`);
920
+ if (typeof request.id !== "string" || !ASSERTION_ID.test(request.id)) refuse("V01", "assertion id must look like a:<16 lowercase hex>:<seq>; list ids with vmem assertions <vault> --history");
921
+ const id = request.id, ctx = context(home, { vault: request.vault, channel: request.channel }, "assertion purges");
922
+ // The reason is written into every purged line, so it is screened like any other write: a purge must not add the
923
+ // class of content it exists to remove.
924
+ const screened = screenContent(reason, ctx.vault, ctx.config).filter(issue => issue.severity === "error");
925
+ if (screened.length) refuse(screened[0]!.code, `reason is refused by current policy (${screened[0]!.message}); give a reason without secrets or personal data, for example "evidence_withdrawn"`);
926
+ const read = () => readJournal(ctx.root, ctx.config.denyPaths ?? []);
927
+ const prepare = (journal: VerifiedJournal) => {
928
+ const broken = journal.segments.find(segment => segment.untrusted || segment.unsupported);
929
+ if (broken) refuse("V09", `segment ${broken.segment} fails verification from seq ${(broken.untrusted ?? broken.unsupported)!.seq}, so the whole journal is unverified; purge rewrites verified segments only. Restore the segment from Git, or delete it after checking it, then retry`);
930
+ const found = assertionEntries(journal, id);
931
+ if (!found.length) refuse("V01", `no verified journal entry belongs to ${id}; list assertion ids with vmem assertions ${request.vault} --history`);
932
+ const remaining = found.filter(entry => entry.purged === undefined);
933
+ if (!remaining.length) refuse("V01", `${id} is already purged (${JSON.stringify(found.find(entry => entry.purged)!.purged)}); there is no payload left to remove`);
934
+ return { journal, found, remaining, fingerprint: purgeFingerprint(ctx.root, id, reason, remaining, journal) };
935
+ };
936
+ let plan = prepare(read());
937
+ receipt.fingerprint = plan.fingerprint;
938
+ receipt.alreadyPurged = plan.found.length - plan.remaining.length;
939
+ receipt.omitted = Math.max(0, plan.remaining.length - PURGE_LIST_LIMIT);
940
+ receipt.entries = plan.remaining.slice(0, PURGE_LIST_LIMIT).map(entry => ({ segment: entry.seg, seq: entry.seq, op: entry.op, hash: entry.hash }));
941
+ receipt.segments = [...new Set(plan.remaining.map(entry => entry.seg))].sort().map(segment => {
942
+ const report = plan.journal.segments.find(value => value.segment === segment)!;
943
+ return { segment, entries: plan.remaining.filter(entry => entry.seg === segment).length, bytes: report.verifiedBytes, after: report.verifiedBytes };
944
+ });
945
+ if (request.confirm !== true) { receipt.ok = true; return receipt; }
946
+ if (request.fingerprint !== plan.fingerprint) refuse("V09", `stale or missing purge fingerprint for ${id}; the journal changed since that preview. Run vmem assertions purge ${request.vault} ${id} --reason again and confirm with the fingerprint it returns`);
947
+ lock = acquire(ctx.root);
948
+ plan = prepare(read());
949
+ if (lock && plan.fingerprint !== receipt.fingerprint) refuse("V09", `the journal changed while the purge waited for assertions.lock; ${id} was not rewritten. Request a fresh preview and confirm again`);
950
+ const at = instant(options.now ?? new Date()), dir = join(ctx.root, ASSERTIONS_DIR), marker = { at, reason };
951
+ for (const segment of receipt.segments.map(value => value.segment)) {
952
+ const report = plan.journal.segments.find(value => value.segment === segment)!;
953
+ const file = join(dir, `${segment}.jsonl`);
954
+ const data = readBounded(file, MAX_SEGMENT_BYTES + MAX_BATCH_BYTES * 4);
955
+ if (typeof data === "string") refuse("V09", `segment ${segment} could not be reread (${data}); restore it from Git before purging`);
956
+ if (data.length < report.verifiedBytes) refuse("CONCURRENT", `segment ${segment} shrank while it was read; nothing was rewritten, retry the purge`);
957
+ const lines = data.subarray(0, report.verifiedBytes).toString("utf8").split("\n");
958
+ const targets = new Map(plan.remaining.filter(entry => entry.seg === segment).map(entry => [entry.seq, entry]));
959
+ const next: string[] = [];
960
+ for (let index = 0; index < lines.length - 1; index++) {
961
+ const entry = targets.get(index + 1);
962
+ if (!entry) { next.push(lines[index]!); continue; }
963
+ const { payload: _payload, purged: _purged, ...hashed } = entry as unknown as Record<string, unknown>;
964
+ next.push(canonical({ ...hashed, purged: marker }));
965
+ }
966
+ const buffer = Buffer.from(next.map(line => line + "\n").join(""), "utf8");
967
+ // Verify the candidate before it can replace anything: the rewritten lines are what later reads trust, so a
968
+ // shape the verifier would reject must never reach the segment.
969
+ const check = verifySegment(segment, buffer);
970
+ if (check.untrusted || check.unsupported || check.tornTail || check.partialBatch || check.verifiedBytes !== buffer.length || check.entries.length !== report.entries.length)
971
+ refuse("V09", `the rewritten bytes of segment ${segment} did not verify (${check.untrusted?.reason ?? (check.unsupported ? `unsupported schema version ${JSON.stringify(check.unsupported.version)}` : "an entry count or batch mismatch")}); segment ${segment} was not renamed and is unchanged. Keep this segment and retry once the cause is fixed`);
972
+ const temporary = join(dir, `.${segment}.jsonl.${randomBytes(6).toString("hex")}.tmp`);
973
+ let fd: number;
974
+ try { fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o644); }
975
+ catch { refuse("IO", `the purge could not create a temporary file in ${ASSERTIONS_DIR}; check free space and directory permissions, then retry`); }
976
+ try { writeFileSync(fd, buffer); fsyncSync(fd); }
977
+ catch (caught) {
978
+ try { unlinkSync(temporary); } catch { receipt.issues.push({ code: "CLEANUP", severity: "warning", message: `${temporary.slice(dir.length + 1)} could not be removed; delete it from ${ASSERTIONS_DIR} once no purge is running` }); }
979
+ refuse("IO", `the purge could not write the temporary file for segment ${segment} (${(caught as NodeJS.ErrnoException).code ?? "write failed"}); nothing was renamed, so check free space and directory permissions, then retry`);
980
+ } finally { closeSync(fd); }
981
+ try { renameSync(temporary, file); }
982
+ catch (caught) {
983
+ try { unlinkSync(temporary); } catch { receipt.issues.push({ code: "CLEANUP", severity: "warning", message: `${temporary.slice(dir.length + 1)} could not be removed; delete it from ${ASSERTIONS_DIR} once no purge is running` }); }
984
+ throw caught;
985
+ }
986
+ syncDirectory(dir);
987
+ // The segment is rewritten from here on: report it, so a failure on a later segment never reads as "nothing happened".
988
+ receipt.applied = true; receipt.at = at;
989
+ const written = receipt.segments.find(value => value.segment === segment)!;
990
+ written.after = buffer.length;
991
+ if (data.length > report.verifiedBytes) receipt.recovery.push(`dropped ${data.length - report.verifiedBytes} unverified bytes after seq ${report.tail?.seq ?? 0} of segment ${segment} while purging`);
992
+ }
993
+ // The disposable projection stores canonical entries, payloads included, so it is replaced with one built from
994
+ // the purged journal while the lock is still held. Its removal comes first, so a failed rebuild leaves no copy.
995
+ const roots = ctx.config.vaults.map(value => value.path), index = assertionIndexPath(home, ctx.root, roots);
996
+ try {
997
+ try { unlinkSync(index); } catch (caught) { if ((caught as NodeJS.ErrnoException).code !== "ENOENT") throw caught; }
998
+ rebuildAssertionIndex(home, ctx.root, read(), roots);
999
+ } catch (caught) {
1000
+ receipt.issues.push({ code: "INDEX", severity: "warning", message: `the payloads are gone from the segments but the derived index at ${index} was not refreshed (${(caught as NodeJS.ErrnoException).code ?? (caught as Error).message}); delete that file and the next read rebuilds it` });
1001
+ }
1002
+ receipt.ok = true;
1003
+ } catch (caught) {
1004
+ if (caught instanceof Refused) receipt.issues.push(...caught.issues);
1005
+ else if (caught instanceof Coded) receipt.issues.push(err(caught.code, caught.message));
1006
+ else if (receipt.applied) receipt.issues.push(err("DURABILITY", `the purge rewrote ${receipt.segments.filter(value => value.after !== value.bytes).length} of ${receipt.segments.length} segment(s) and a later step failed (${(caught as NodeJS.ErrnoException).code ?? (caught as Error).message}); the remaining entries are still in the journal. Request a fresh preview and confirm again to finish`));
1007
+ else receipt.issues.push(err("IO", "assertion purge failed on file I/O; check permissions and disk space, then retry"));
1008
+ receipt.ok = false;
1009
+ } finally {
1010
+ if (lock) release(lock, receipt.issues);
1011
+ }
1012
+ return receipt;
1013
+ }