@dreamforgestudiollc/emet 0.3.5 → 0.3.7

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 (103) hide show
  1. package/.env.example +29 -0
  2. package/CHANGELOG.md +49 -11
  3. package/CHARTER.md +1 -1
  4. package/CONTRIBUTING.md +21 -0
  5. package/README.md +25 -10
  6. package/RELEASE_NOTES-0.2.6.md +43 -0
  7. package/RELEASE_NOTES-0.3.6.md +29 -0
  8. package/RELEASE_NOTES-0.3.7.md +19 -0
  9. package/SECURITY.md +13 -0
  10. package/docs/BOTS.md +4 -4
  11. package/docs/DEPLOY.md +23 -4
  12. package/docs/ERROR-CODES-SPEC.md +4 -0
  13. package/docs/ERROR-CODES.md +7 -0
  14. package/docs/GUIDED-SETUP.md +1 -1
  15. package/docs/ROADMAP.md +62 -49
  16. package/docs/SETUP.md +11 -1
  17. package/docs/SUBKEYS.md +3 -1
  18. package/docs/continuity-currency-statechart.md +34 -0
  19. package/docs/features/README.md +21 -0
  20. package/docs/features/access.md +28 -0
  21. package/docs/features/documents.md +35 -0
  22. package/docs/features/errors.md +32 -0
  23. package/docs/features/gems.md +31 -0
  24. package/docs/features/memory.md +29 -0
  25. package/docs/features/pages.md +28 -0
  26. package/docs/features/record.md +27 -0
  27. package/docs/features/search.md +27 -0
  28. package/docs/features/startup.md +29 -0
  29. package/docs/features/subkeys.md +30 -0
  30. package/docs/features/transcripts.md +33 -0
  31. package/docs/per-tag-handoff-statechart.md +147 -0
  32. package/docs/subkey-session-statechart.md +57 -0
  33. package/package.json +6 -2
  34. package/server.json +27 -2
  35. package/src/annotations.js +5 -3
  36. package/src/attribution.js +2 -2
  37. package/src/carry-forward-close.js +1 -1
  38. package/src/chooser.js +74 -3
  39. package/src/conformance.js +2 -0
  40. package/src/continuity-currency-statechart.js +139 -0
  41. package/src/continuity-currency.js +869 -0
  42. package/src/database.js +1 -1
  43. package/src/dispatch.js +1 -1
  44. package/src/error-codes.js +7 -0
  45. package/src/gem-check.js +4 -1
  46. package/src/grants.js +28 -5
  47. package/src/host-reach.js +1 -1
  48. package/src/http-remote.js +29 -5
  49. package/src/index.js +3 -2
  50. package/src/invites.js +2 -2
  51. package/src/owl.js +12 -11
  52. package/src/pages.js +15 -0
  53. package/src/per-tag-handoff-statechart.js +264 -0
  54. package/src/per-tag-handoff.js +988 -0
  55. package/src/persons.js +16 -0
  56. package/src/session-graph.js +123 -12
  57. package/src/session.js +56 -12
  58. package/src/setup.js +32 -11
  59. package/src/startup-pages.js +13 -2
  60. package/src/subkey-lifecycle.js +105 -0
  61. package/src/subkey-session-statechart.js +253 -0
  62. package/src/subkeys.js +648 -89
  63. package/src/tools.js +171 -51
  64. package/src/transcript-session.js +2 -2
  65. package/src/version.js +1 -1
  66. package/templates/INDEX.md +1 -0
  67. package/templates/SESSIONDISPOSITION.md +2 -2
  68. package/templates/TAGHANDOFF.md +45 -0
  69. package/verification/continuity-currency/ContinuityCurrency.cfg +12 -0
  70. package/verification/continuity-currency/ContinuityCurrency.tla +239 -0
  71. package/verification/continuity-currency/tlc-output.txt +32 -0
  72. package/verification/continuity-currency/view.mjs +54 -0
  73. package/verification/load-gate/load-gate.mjs +1 -1
  74. package/verification/per-tag-handoff/PerTagHandoff.cfg +10 -0
  75. package/verification/per-tag-handoff/PerTagHandoff.tla +191 -0
  76. package/verification/per-tag-handoff/StampCounter.cfg +10 -0
  77. package/verification/per-tag-handoff/out/report.md +6 -0
  78. package/verification/per-tag-handoff/out-counter/chart.mmd +30 -0
  79. package/verification/per-tag-handoff/out-counter/report.md +15 -0
  80. package/verification/per-tag-handoff/out-counter/tlc.out +130 -0
  81. package/verification/per-tag-handoff/split/PerTagConflict.cfg +6 -0
  82. package/verification/per-tag-handoff/split/PerTagConflict.tla +104 -0
  83. package/verification/per-tag-handoff/split/PerTagTime.cfg +8 -0
  84. package/verification/per-tag-handoff/split/PerTagTime.tla +100 -0
  85. package/verification/per-tag-handoff/split/conflict-chart.mmd +47 -0
  86. package/verification/per-tag-handoff/split/conflict-report.md +8 -0
  87. package/verification/per-tag-handoff/split/conflict-tlc.txt +19 -0
  88. package/verification/per-tag-handoff/split/conflict-view.mjs +34 -0
  89. package/verification/per-tag-handoff/split/time-chart.mmd +44 -0
  90. package/verification/per-tag-handoff/split/time-report.md +8 -0
  91. package/verification/per-tag-handoff/split/time-tlc.txt +19 -0
  92. package/verification/per-tag-handoff/split/time-view.mjs +33 -0
  93. package/verification/per-tag-handoff/tlc-output.txt +19 -0
  94. package/verification/per-tag-handoff/v1-draft/PerTagHandoff.cfg +5 -0
  95. package/verification/per-tag-handoff/v1-draft/PerTagHandoff.tla +94 -0
  96. package/verification/per-tag-handoff/v1-draft/out/chart.mmd +37 -0
  97. package/verification/per-tag-handoff/v1-draft/out/report.md +7 -0
  98. package/verification/per-tag-handoff/v1-draft/out/tlc.out +19 -0
  99. package/verification/per-tag-handoff/v1-draft/view.mjs +20 -0
  100. package/verification/per-tag-handoff/view.mjs +31 -0
  101. package/verification/subkey-session/SubkeySession.cfg +11 -0
  102. package/verification/subkey-session/SubkeySession.tla +254 -0
  103. package/verification/subkey-session/tlc-output.txt +13 -0
@@ -0,0 +1,869 @@
1
+ /**
2
+ * EMET - Enduring Memory & Epistemic Tiers
3
+ * Copyright (c) 2026 Dreamforge Studio LLC
4
+ *
5
+ * Licensed under the MIT License - see LICENSE
6
+ *
7
+ * Continuity-currency gate. A read-time comparison of the served
8
+ * HANDOFF against the live material episodic tip. This is not wiki page
9
+ * currency (`src/currency.js`): that class is about a topic page. This one
10
+ * is tip-lag. HANDOFF and STATE are records. This module never writes them,
11
+ * never supersedes them, and never blocks a call. Phase 2 block stays off.
12
+ */
13
+
14
+ import crypto from 'crypto';
15
+ import { setting } from './env.js';
16
+ import { parseMetadata } from './metadata.js';
17
+ import { handoffDoc } from './session.js';
18
+ import { COLLECTION_PREFIX } from './database.js';
19
+ import { tagHandoffMode, hubTag, worstStatus, partitionEpisodic, openSessionsFromRows, staleOpenHours, writeTagRegistry, OPEN_SESSION_LOOKBACK_MS } from './per-tag-handoff.js';
20
+
21
+ export const CONTINUITY_CURRENCY_FLAG = 'EMET_CONTINUITY_CURRENCY';
22
+ /** Reserved name. This revision does not read it to block. */
23
+ export const CONTINUITY_CURRENCY_BLOCK_FLAG = 'EMET_CONTINUITY_CURRENCY_BLOCK';
24
+ export const CONTINUITY_CURRENCY_BLOCK_ENABLED = false;
25
+
26
+ /**
27
+ * Start of the UTC day 2026-09-27 (8:00 PM EDT on 2026-09-26).
28
+ * Audit 1.5c renamed the write argument to `source` and did not change stored rows. A registered
29
+ * tag is required on a transcript write (audit 1.5d). An episodic save does
30
+ * not require one. A material row with no registered source written before
31
+ * this instant is legacy (pre-attribution): the reading counts it and lists
32
+ * its ids, and it does not make the overall status warn. A row at or after
33
+ * this instant with no registered source still warns. A row with no
34
+ * timestamp, or a timestamp that does not parse, still warns. A row with no
35
+ * id is judged by its timestamp the same way. This check does not read
36
+ * EMET_CONTINUITY_CURRENCY_BLOCK.
37
+ */
38
+ export const TAG_ATTRIBUTION_BEGAN = '2026-09-27T00:00:00.000Z';
39
+ export const LEGACY_PRE_ATTRIBUTION = 'legacy (pre-attribution)';
40
+ export const LEGACY_CUTOFF_BASIS = 'after_last_unsourced_episodic';
41
+
42
+ /** No install-specific display-name aliases. The stored source is the source. */
43
+ const CONTINUITY_SOURCE_ALIAS = Object.freeze({});
44
+
45
+ /** No install-specific noted-legacy rows. A public store starts empty. */
46
+ const NOTED_LEGACY = Object.freeze([]);
47
+
48
+ /** Preferred tags, any one, compared case-insensitively. */
49
+ export const PREFERRED_TAGS = Object.freeze([
50
+ 'material', 'board', 'decision', 'deploy', 'go-live',
51
+ 'reconnect', 'reminder-clear', 'handoff', 'handoff-rewrite', 'handoff-relevant'
52
+ ]);
53
+
54
+ const HARD_EXCLUDE = new Set(['scratch', 'probe', 'test', 'superseded', 'ended']);
55
+ const DIAGNOSIS = new Set(['diagnosis', 'transcript-flag', 'transcript-flag-only', 'transcript-flags']);
56
+ const PROJECT_EFFECT = Object.freeze([
57
+ /\bhandoff\b/i,
58
+ /\bSTATE\b/,
59
+ /\bstate\.md\b/i,
60
+ /\bboard\b/i,
61
+ /\bdeploy\b/i,
62
+ /\breconnect\b/i,
63
+ /reminder-clear/i,
64
+ /user decision/i
65
+ ]);
66
+
67
+ const SUMMARY_CHARS = 160;
68
+ const NEWER_LIST_CAP = 20;
69
+
70
+ const EPISODIC_PROJECTION = Object.freeze({
71
+ _id: 0,
72
+ id: 1,
73
+ timestamp: 1,
74
+ content: 1,
75
+ context: 1,
76
+ metadata: 1,
77
+ tags: 1,
78
+ importance_bucket: 1,
79
+ importance_degree: 1,
80
+ kind: 1,
81
+ is_live: 1,
82
+ superseded_by: 1,
83
+ ended: 1,
84
+ valid_until: 1,
85
+ layer_tip: 1
86
+ });
87
+
88
+ const EPISODIC_QUERY = Object.freeze({
89
+ $or: [
90
+ { id: { $gte: 1 } },
91
+ { id: { $regex: '^\\d+$' } },
92
+ { layer_tip: { $gte: 1 } },
93
+ { layer_tip: { $regex: '^\\d+$' } },
94
+ { 'metadata.layer_tip': { $gte: 1 } },
95
+ { 'metadata.layer_tip': { $regex: '^\\d+$' } },
96
+ { metadata: { $regex: '"layer_tip"' } }
97
+ ]
98
+ });
99
+
100
+ const SESSION_PROJECTION = Object.freeze({
101
+ _id: 0,
102
+ episodic_id: 1,
103
+ closed: 1,
104
+ handoff: 1,
105
+ handoff_version: 1
106
+ });
107
+
108
+ const SESSION_QUERY = Object.freeze({
109
+ $or: [
110
+ { closed: true },
111
+ { handoff: true }
112
+ ]
113
+ });
114
+
115
+ /** Phase 1 is on only when the setting is the digit 1. Anything else is off. */
116
+ export function continuityCurrencyEnabled() {
117
+ return setting('CONTINUITY_CURRENCY') === '1';
118
+ }
119
+
120
+ /**
121
+ * Phase 2 is not enabled in this revision. The reserved setting is reported
122
+ * and ignored. This revision does not turn a block on.
123
+ */
124
+ export function continuityCurrencyBlockEnabled() {
125
+ return CONTINUITY_CURRENCY_BLOCK_ENABLED;
126
+ }
127
+
128
+ export function continuityCurrencyBlockRequested() {
129
+ return setting('CONTINUITY_CURRENCY_BLOCK') === '1';
130
+ }
131
+
132
+ function finiteId(value) {
133
+ if (typeof value === 'string' && /^\d+$/.test(value.trim())) value = Number(value.trim());
134
+ if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) return null;
135
+ return value;
136
+ }
137
+
138
+ function epochMs(value) {
139
+ if (value == null || value === '') return null;
140
+ if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value.getTime();
141
+ if (typeof value === 'number' && Number.isFinite(value)) {
142
+ if (value > 1e12) return value;
143
+ if (value > 1e9) return Math.round(value * 1000);
144
+ return null;
145
+ }
146
+ if (typeof value === 'string') {
147
+ const parsed = Date.parse(value);
148
+ return Number.isNaN(parsed) ? null : parsed;
149
+ }
150
+ return null;
151
+ }
152
+
153
+ function isoFromMs(ms) {
154
+ if (ms == null) return null;
155
+ const date = new Date(ms);
156
+ return Number.isNaN(date.getTime()) ? null : date.toISOString();
157
+ }
158
+
159
+ function tagsOf(entry) {
160
+ const md = parseMetadata(entry && entry.metadata);
161
+ const raw = Array.isArray(md.tags) ? md.tags : (Array.isArray(entry && entry.tags) ? entry.tags : []);
162
+ const out = [];
163
+ for (const tag of raw) {
164
+ const name = String(tag == null ? '' : tag).trim().toLowerCase();
165
+ if (name && !out.includes(name)) out.push(name);
166
+ }
167
+ return out;
168
+ }
169
+
170
+ function bucketOf(entry) {
171
+ const md = parseMetadata(entry && entry.metadata);
172
+ return String(md.importance_bucket || (entry && entry.importance_bucket) || '').trim().toLowerCase();
173
+ }
174
+
175
+ function degreeOf(entry) {
176
+ const md = parseMetadata(entry && entry.metadata);
177
+ return String(md.importance_degree || (entry && entry.importance_degree) || '').trim().toLowerCase();
178
+ }
179
+
180
+ function kindOf(entry) {
181
+ const md = parseMetadata(entry && entry.metadata);
182
+ return String(md.kind || (entry && entry.kind) || '').trim().toLowerCase();
183
+ }
184
+
185
+ function oneLine(text) {
186
+ const line = String(text || '').split(/\r?\n/).map((part) => part.trim()).find(Boolean) || '';
187
+ const flat = line.replace(/\s+/g, ' ').trim();
188
+ const chars = Array.from(flat);
189
+ if (chars.length <= SUMMARY_CHARS) return flat;
190
+ return `${chars.slice(0, SUMMARY_CHARS - 1).join('')}…`;
191
+ }
192
+
193
+ function projectEffect(text) {
194
+ const body = String(text || '');
195
+ return PROJECT_EFFECT.some((pattern) => pattern.test(body));
196
+ }
197
+
198
+ function hardExclude(entry, tags, nowMs) {
199
+ if (!entry || typeof entry !== 'object') return 'unreadable';
200
+ if (entry.is_live === false) return 'ended';
201
+ const md = parseMetadata(entry.metadata);
202
+ const superseded = entry.superseded_by ?? md.superseded_by;
203
+ if (superseded != null && superseded !== '') return 'superseded';
204
+ if (entry.ended === true || md.ended === true) return 'ended';
205
+ const until = epochMs(entry.valid_until ?? md.valid_until);
206
+ if (until != null && until <= nowMs) return 'ended';
207
+ if (bucketOf(entry) === 'scratch') return 'scratch';
208
+ for (const tag of tags) if (HARD_EXCLUDE.has(tag)) return tag;
209
+ return null;
210
+ }
211
+
212
+ function diagnosisOnly(entry, tags) {
213
+ if (tags.some((tag) => DIAGNOSIS.has(tag))) return true;
214
+ return DIAGNOSIS.has(kindOf(entry));
215
+ }
216
+
217
+ function fallbackTags(entry, tags) {
218
+ const binding = tags.includes('binding') || tags.includes('durable') || bucketOf(entry) === 'binding' || bucketOf(entry) === 'durable';
219
+ const event = tags.includes('event') || bucketOf(entry) === 'event';
220
+ const high = degreeOf(entry) === 'high' || tags.includes('high');
221
+ if (!projectEffect(entry && entry.content)) return null;
222
+ if (binding) return tags.filter((tag) => tag === 'binding' || tag === 'durable');
223
+ if (event && high) return tags.filter((tag) => tag === 'event' || tag === 'high');
224
+ return null;
225
+ }
226
+
227
+ /**
228
+ * One episodic row. `pointers.closeVerification` holds ids from closed
229
+ * sessions and the handoff's own close-verification claim. `pointers.layerTip`
230
+ * holds ids named by a layer-tip field.
231
+ * Scratch, superseded, ended, probe, and test lose before a preferred tag.
232
+ * A preferred tag is the only thing that keeps a diagnosis-only or
233
+ * transcript-flags row. Those exclusions run before any pointer match.
234
+ * Fallback is pilot-logged and is not, by itself, a future block.
235
+ */
236
+ export function classifyEpisodic(entry, pointers, nowMs = Date.now()) {
237
+ const tags = tagsOf(entry);
238
+ const excluded = hardExclude(entry, tags, nowMs);
239
+ if (excluded) return { material: false, excluded, tags, basis: null, matching: [], pilot_logged: false };
240
+ const matching = PREFERRED_TAGS.filter((tag) => tags.includes(tag));
241
+ if (matching.length) {
242
+ return { material: true, excluded: null, tags, basis: 'preferred_tag', matching, pilot_logged: false };
243
+ }
244
+ if (diagnosisOnly(entry, tags)) {
245
+ return { material: false, excluded: 'diagnosis', tags, basis: null, matching: [], pilot_logged: false };
246
+ }
247
+ const id = finiteId(entry && entry.id);
248
+ if (id != null && pointers && pointers.closeVerification && pointers.closeVerification.has(id)) {
249
+ return { material: true, excluded: null, tags, basis: 'close_verification', matching: [], pilot_logged: false };
250
+ }
251
+ if (id != null && pointers && pointers.layerTip && pointers.layerTip.has(id)) {
252
+ return { material: true, excluded: null, tags, basis: 'layer_tip', matching: [], pilot_logged: false };
253
+ }
254
+ const fallback = fallbackTags(entry, tags);
255
+ if (fallback) {
256
+ return { material: true, excluded: null, tags, basis: 'fallback', matching: fallback, pilot_logged: true };
257
+ }
258
+ return { material: false, excluded: null, tags, basis: null, matching: [], pilot_logged: false };
259
+ }
260
+
261
+ function collectIds(text) {
262
+ const ids = [];
263
+ const body = String(text || '');
264
+ // A year-month or a full date is not an id.
265
+ const patterns = [
266
+ /\bepisodic(?:[\s_-]*(?:id|entry|#))?[\s:#_-]*#?\s*(\d{1,12})\b(?!-\d{2}(?:-\d{2})?\b)/gi,
267
+ /\brecord\s+id\s+#?\s*(\d{1,12})\b(?!-\d{2}(?:-\d{2})?\b)/gi
268
+ ];
269
+ for (const pattern of patterns) {
270
+ for (const match of body.matchAll(pattern)) {
271
+ const id = finiteId(match[1]);
272
+ if (id != null) ids.push(id);
273
+ }
274
+ }
275
+ return ids;
276
+ }
277
+
278
+ function isCloseHeading(line) {
279
+ return /^#{1,6}\s/.test(line) && (/§\s*6\b/i.test(line) || /close verification/i.test(line));
280
+ }
281
+
282
+ /** The label starts the line. A bullet or a bold mark may precede it. */
283
+ function isInlineCloseLine(line) {
284
+ const text = String(line).replace(/^\s+/, '');
285
+ const unbulleted = text.replace(/^(?:[-*+]|\d+[.)])\s+/, '');
286
+ const unbold = unbulleted.replace(/^(?:\*\*|__)/, '').replace(/^\s+/, '');
287
+ return /^close verification\b/i.test(unbold);
288
+ }
289
+
290
+ /**
291
+ * Close-verification sites in document order. A newest-first handoff puts the
292
+ * current session first and keeps older `## §6` tables below it. The first
293
+ * site is the one in force: an inline "Close verification" line, or a §6
294
+ * table. A retained table further down is not the claim.
295
+ */
296
+ function closeVerificationSites(content) {
297
+ const lines = String(content || '').split(/\n/);
298
+ const sites = [];
299
+ for (let i = 0; i < lines.length; i++) {
300
+ const line = lines[i];
301
+ if (isCloseHeading(line)) {
302
+ const section = [line];
303
+ let j = i + 1;
304
+ while (j < lines.length && !/^#{1,6}\s/.test(lines[j])) section.push(lines[j++]);
305
+ const sessionLine = section.find((row) => /session record/i.test(row));
306
+ const ids = sessionLine ? collectIds(sessionLine) : collectIds(section.join('\n'));
307
+ if (ids.length) sites.push(ids[0]);
308
+ i = j - 1;
309
+ continue;
310
+ }
311
+ if (isInlineCloseLine(line)) {
312
+ const ids = collectIds(line);
313
+ if (ids.length) sites.push(ids[0]);
314
+ }
315
+ }
316
+ return sites;
317
+ }
318
+
319
+ /**
320
+ * What the served HANDOFF claims is current.
321
+ * 1. The episodic id in the first close verification in the document. On a
322
+ * newest-first handoff that is the current session: an inline line that
323
+ * starts with "Close verification" (a bullet or bold mark may precede it),
324
+ * or a §6 table when that is the first close verification. A mention later
325
+ * in a line is not a close verification. A later retained §6 table is not
326
+ * used. A year-month or a full date, such as 2026-11 or 2026-11-06, is not an id.
327
+ * 2. Else the episodic id stored on the session that wrote this HANDOFF version.
328
+ * 3. Else the highest episodic id explicitly cited in the body.
329
+ * 4. Else updated_at. A version number alone is not a claim that can see lag.
330
+ */
331
+ export function handoffClaim(handoff, sessions = []) {
332
+ const content = handoff && typeof handoff.content === 'string' ? handoff.content : '';
333
+ const sites = closeVerificationSites(content);
334
+ if (sites.length) return { cited_episodic_id: sites[0], claim_basis: 'close_receipt' };
335
+ const version = finiteId(handoff && handoff.version);
336
+ if (version != null) {
337
+ const tied = [];
338
+ for (const row of sessions || []) {
339
+ if (!row || row.handoff !== true) continue;
340
+ if (finiteId(row.handoff_version) !== version) continue;
341
+ const id = finiteId(row.episodic_id);
342
+ if (id != null) tied.push(id);
343
+ }
344
+ if (tied.length) return { cited_episodic_id: Math.max(...tied), claim_basis: 'session_graph' };
345
+ }
346
+ const cited = collectIds(content);
347
+ if (cited.length) return { cited_episodic_id: Math.max(...cited), claim_basis: 'body_citation' };
348
+ if (epochMs(handoff && handoff.updated_at) != null) return { cited_episodic_id: null, claim_basis: 'updated_at' };
349
+ return { cited_episodic_id: null, claim_basis: 'version_only' };
350
+ }
351
+
352
+ /**
353
+ * The title and the first body section. A level-1 title does not end the
354
+ * section. The next heading at that body level, or higher, does. A retained
355
+ * section below that line is not the current note.
356
+ */
357
+ function currentSection(content) {
358
+ const text = String(content || '');
359
+ const lines = text.split('\n');
360
+ let bodyAt = -1;
361
+ let bodyLevel = 0;
362
+ let sawTitle = false;
363
+ for (let i = 0; i < lines.length; i++) {
364
+ const match = /^(#{1,6})\s+\S/.exec(lines[i]);
365
+ if (!match) continue;
366
+ const level = match[1].length;
367
+ if (!sawTitle && level === 1 && bodyAt < 0) {
368
+ sawTitle = true;
369
+ continue;
370
+ }
371
+ if (bodyAt < 0) {
372
+ bodyAt = i;
373
+ bodyLevel = level;
374
+ continue;
375
+ }
376
+ if (level <= bodyLevel) return lines.slice(0, i).join('\n');
377
+ }
378
+ return text;
379
+ }
380
+
381
+ function documentedNoOp(content) {
382
+ return /documented\s+no-?op\b/i.test(currentSection(content));
383
+ }
384
+
385
+ function pointerSets(entries, sessions, claimId) {
386
+ const closeVerification = new Set();
387
+ const layerTip = new Set();
388
+ if (claimId != null) closeVerification.add(claimId);
389
+ for (const row of sessions || []) {
390
+ if (!row || row.closed !== true) continue;
391
+ const id = finiteId(row.episodic_id);
392
+ if (id != null) closeVerification.add(id);
393
+ }
394
+ for (const entry of entries || []) {
395
+ const md = parseMetadata(entry && entry.metadata);
396
+ const tip = finiteId(md.layer_tip != null ? md.layer_tip : entry && entry.layer_tip);
397
+ if (tip != null) layerTip.add(tip);
398
+ }
399
+ return { closeVerification, layerTip };
400
+ }
401
+
402
+ function sha256Of(handoff) {
403
+ if (handoff && typeof handoff.sha256 === 'string' && /^[a-f0-9]{64}$/i.test(handoff.sha256)) {
404
+ return { sha256: handoff.sha256.toLowerCase(), sha256_source: 'stored' };
405
+ }
406
+ if (handoff && typeof handoff.content === 'string') {
407
+ return {
408
+ sha256: crypto.createHash('sha256').update(handoff.content, 'utf8').digest('hex'),
409
+ sha256_source: 'computed'
410
+ };
411
+ }
412
+ return { sha256: null, sha256_source: null };
413
+ }
414
+
415
+ function envelope(status, extra = {}) {
416
+ const blockIgnored = extra.block_requested === true;
417
+ return {
418
+ gate: 'continuity-currency',
419
+ flag: CONTINUITY_CURRENCY_FLAG,
420
+ phase: 1,
421
+ status,
422
+ does_not_block: true,
423
+ block_enabled: false,
424
+ block_ignored: blockIgnored,
425
+ ...(blockIgnored ? {
426
+ block_note: 'The block stays off. EMET_CONTINUITY_CURRENCY_BLOCK is not applied.'
427
+ } : {}),
428
+ ...extra,
429
+ does_not_block: true,
430
+ block_enabled: false
431
+ };
432
+ }
433
+
434
+ function handoffFields(handoff, claim) {
435
+ const digest = sha256Of(handoff);
436
+ return {
437
+ doc_id: (handoff && handoff.doc_id) || handoffDoc(),
438
+ version: handoff && handoff.version != null ? handoff.version : null,
439
+ sha256: digest.sha256,
440
+ sha256_source: digest.sha256_source,
441
+ updated_at: isoFromMs(epochMs(handoff && handoff.updated_at)),
442
+ cited_episodic_id: claim ? claim.cited_episodic_id : null,
443
+ claim_basis: claim ? claim.claim_basis : null
444
+ };
445
+ }
446
+
447
+ function tipFields(row) {
448
+ if (!row) return null;
449
+ return {
450
+ id: row.id,
451
+ timestamp: row.timestamp,
452
+ tags: row.tags,
453
+ basis: row.basis,
454
+ matching_tags: row.matching,
455
+ summary: row.summary
456
+ };
457
+ }
458
+
459
+ function hostAction(fields, tipId, citedId) {
460
+ const version = fields.version == null ? 'the version in force' : String(fields.version);
461
+ const digest = fields.sha256 ? `sha256 ${fields.sha256}` : 'sha256 was not on the stored revision; read_doc it before writing';
462
+ const when = fields.updated_at ? `, updated_at ${fields.updated_at}` : '';
463
+ const cite = tipId == null ? 'the live material tip' : `episodic ${tipId}`;
464
+ const from = citedId == null ? 'No episodic id is cited on the handoff.' : `The handoff cites episodic ${citedId}.`;
465
+ return `Rewrite ${fields.doc_id} whole with supersedes set to ${version} (${digest}${when}). ${from} Cite ${cite} in §6 close verification and name each newer material entry. Do not patch the record. The server does not rewrite HANDOFF or STATE.`;
466
+ }
467
+
468
+ /**
469
+ * Pure comparison. `handoff` is the document in force, or null when it is
470
+ * absent. `entries` are episodic rows. `sessions` are session-graph rows
471
+ * (`episodic_id`, `handoff`, `handoff_version`). Nothing in the arguments
472
+ * is modified.
473
+ */
474
+ export function assessContinuityCurrency({ handoff = null, entries = [], sessions = [], now = Date.now(), blockRequested = false, openEpisodicIds = null } = {}) {
475
+ const nowMs = epochMs(now) || Date.now();
476
+ const block_requested = blockRequested === true;
477
+ const openIds = openEpisodicIds instanceof Set ? openEpisodicIds : null;
478
+ if (!handoff || typeof handoff.content !== 'string') {
479
+ return envelope('no_handoff', {
480
+ block_requested,
481
+ handoff: null,
482
+ material_tip: null,
483
+ documented_no_op: false
484
+ });
485
+ }
486
+ let claim = handoffClaim(handoff, sessions);
487
+ if (openIds && claim.cited_episodic_id != null && openIds.has(claim.cited_episodic_id)) {
488
+ claim = { cited_episodic_id: null, claim_basis: 'open_session' };
489
+ }
490
+ const pointers = pointerSets(entries, sessions, claim.cited_episodic_id);
491
+ if (openIds) for (const id of openIds) pointers.closeVerification.delete(id);
492
+ const classified = [];
493
+ for (const entry of entries || []) {
494
+ const id = finiteId(entry && entry.id);
495
+ if (openIds && id != null && openIds.has(id)) continue;
496
+ const row = classifyEpisodic(entry, pointers, nowMs);
497
+ if (!row.material) continue;
498
+ if (id == null) continue;
499
+ classified.push({
500
+ id,
501
+ timestamp: isoFromMs(epochMs(entry.timestamp)),
502
+ timestamp_ms: epochMs(entry.timestamp),
503
+ tags: row.tags,
504
+ basis: row.basis,
505
+ matching: row.matching,
506
+ pilot_logged: row.pilot_logged === true,
507
+ summary: oneLine(entry.content || entry.context || '')
508
+ });
509
+ }
510
+ classified.sort((a, b) => a.id - b.id);
511
+ const tip = classified.length ? classified[classified.length - 1] : null;
512
+ const claimMs = epochMs(handoff.updated_at);
513
+ let newer = [];
514
+ if (claim.cited_episodic_id != null) {
515
+ newer = classified.filter((row) => row.id > claim.cited_episodic_id);
516
+ } else if (claim.claim_basis === 'updated_at' && claimMs != null) {
517
+ newer = classified.filter((row) => row.timestamp_ms != null && row.timestamp_ms > claimMs);
518
+ }
519
+ const lag = newer.length > 0 && claim.claim_basis !== 'version_only';
520
+ const noOp = documentedNoOp(handoff.content);
521
+ const fields = handoffFields(handoff, claim);
522
+ const fallbackAll = classified.filter((row) => row.pilot_logged).sort((a, b) => b.id - a.id);
523
+ const fallbackLogged = fallbackAll.slice(0, NEWER_LIST_CAP).map((row) => ({
524
+ id: row.id,
525
+ timestamp: row.timestamp,
526
+ tags: row.matching,
527
+ summary: row.summary
528
+ }));
529
+ const shared = {
530
+ block_requested,
531
+ handoff: fields,
532
+ material_tip: tipFields(tip),
533
+ documented_no_op: noOp,
534
+ fallback_logged: fallbackLogged,
535
+ fallback_logged_truncated: fallbackAll.length > fallbackLogged.length
536
+ };
537
+ if (!lag) {
538
+ return envelope(noOp ? 'no_op' : 'current', shared);
539
+ }
540
+ const listed = [...newer].sort((a, b) => b.id - a.id).slice(0, NEWER_LIST_CAP).map((row) => ({
541
+ id: row.id,
542
+ timestamp: row.timestamp,
543
+ tags: row.tags,
544
+ matching_tags: row.matching,
545
+ basis: row.basis,
546
+ summary: row.summary
547
+ }));
548
+ if (tip && newer.some((row) => row.id === tip.id) && !listed.some((row) => row.id === tip.id)) {
549
+ listed.push({
550
+ id: tip.id,
551
+ timestamp: tip.timestamp,
552
+ tags: tip.tags,
553
+ matching_tags: tip.matching,
554
+ basis: tip.basis,
555
+ summary: tip.summary
556
+ });
557
+ }
558
+ const matching = [];
559
+ for (const row of newer) {
560
+ for (const tag of row.matching) if (!matching.includes(tag)) matching.push(tag);
561
+ }
562
+ const blockEligible = newer.some((row) => row.basis !== 'fallback');
563
+ return envelope('warn', {
564
+ ...shared,
565
+ matching_tags: matching,
566
+ lag_span: {
567
+ cited_episodic_id: claim.cited_episodic_id,
568
+ claim_updated_at: fields.updated_at,
569
+ material_tip_id: tip ? tip.id : null,
570
+ material_tip_timestamp: tip ? tip.timestamp : null,
571
+ newer_material_count: newer.length,
572
+ claim_basis: claim.claim_basis
573
+ },
574
+ newer_material: listed,
575
+ newer_material_truncated: newer.length > listed.length,
576
+ fallback_only: !blockEligible,
577
+ block_eligible: blockEligible,
578
+ recommended_host_action: hostAction(fields, tip ? tip.id : null, claim.cited_episodic_id)
579
+ });
580
+ }
581
+
582
+ export function continuityCurrencyUnreadable() {
583
+ return envelope('unreadable', {
584
+ block_requested: continuityCurrencyBlockRequested(),
585
+ handoff: null,
586
+ material_tip: null,
587
+ documented_no_op: false,
588
+ note: 'The continuity-currency comparison could not be read. Nothing was blocked and nothing was written.'
589
+ });
590
+ }
591
+
592
+ function projectRow(row, projection) {
593
+ const out = {};
594
+ if (!row || typeof row !== 'object') return out;
595
+ for (const [key, flag] of Object.entries(projection || {})) {
596
+ if (!flag || key === '_id') continue;
597
+ if (Object.prototype.hasOwnProperty.call(row, key)) out[key] = row[key];
598
+ }
599
+ return out;
600
+ }
601
+
602
+ function dedupeById(rows, nowMs) {
603
+ const index = new Map();
604
+ const out = [];
605
+ const excluded = (row) => hardExclude(row, tagsOf(row), nowMs) != null;
606
+ for (const row of rows || []) {
607
+ const id = finiteId(row && row.id);
608
+ if (id == null) {
609
+ out.push(row);
610
+ continue;
611
+ }
612
+ if (!index.has(id)) {
613
+ index.set(id, out.length);
614
+ out.push(row);
615
+ continue;
616
+ }
617
+ const at = index.get(id);
618
+ if (excluded(out[at]) && !excluded(row)) out[at] = row;
619
+ }
620
+ return out;
621
+ }
622
+
623
+ /**
624
+ * One find. The projection is applied again so a driver that returns extra
625
+ * fields still feeds the gate only the fields the comparison uses, including
626
+ * the episodic text. Rows that share an id are kept once, and the copy that
627
+ * is not excluded wins.
628
+ */
629
+ async function readProjected(collection, query, projection, sort, nowMs) {
630
+ let cursor = collection.find(query, { projection });
631
+ if (!cursor || typeof cursor.toArray !== 'function') return [];
632
+ if (sort && typeof cursor.sort === 'function') cursor = cursor.sort(sort);
633
+ const rows = await cursor.toArray();
634
+ if (!Array.isArray(rows)) return [];
635
+ return dedupeById(rows.map((row) => projectRow(row, projection)), nowMs);
636
+ }
637
+
638
+ /**
639
+ * Read the hub handoff, the episodic layer, and session-graph pointers.
640
+ * Find and findOne only. No insert, update, or delete.
641
+ */
642
+ export async function loadContinuityCurrency(db, options = {}) {
643
+ const docId = options.docId || handoffDoc();
644
+ const prefix = options.prefix || COLLECTION_PREFIX;
645
+ const nowMs = epochMs(options.now) || Date.now();
646
+ const handoff = await db.collection('documents').findOne({ doc_id: docId });
647
+ const episodic = await readProjected(
648
+ db.collection(`${prefix}episodic`),
649
+ EPISODIC_QUERY,
650
+ EPISODIC_PROJECTION,
651
+ { id: -1 },
652
+ nowMs
653
+ );
654
+ let sessions = [];
655
+ try {
656
+ sessions = await readProjected(
657
+ db.collection(`${prefix}sessions`),
658
+ SESSION_QUERY,
659
+ SESSION_PROJECTION,
660
+ { episodic_id: -1 },
661
+ nowMs
662
+ );
663
+ } catch {
664
+ sessions = [];
665
+ }
666
+ const assessed = assessContinuityCurrency({
667
+ handoff: handoff ? {
668
+ doc_id: handoff.doc_id,
669
+ version: handoff.version ?? null,
670
+ sha256: handoff.sha256 || null,
671
+ updated_at: handoff.updated_at ?? null,
672
+ content: typeof handoff.content === 'string' ? handoff.content : ''
673
+ } : null,
674
+ entries: episodic,
675
+ sessions,
676
+ now: options.now,
677
+ blockRequested: options.blockRequested != null ? options.blockRequested === true : continuityCurrencyBlockRequested()
678
+ });
679
+ if (tagHandoffMode() === 'off') return assessed;
680
+ try {
681
+ return await perTagCurrency(db, assessed, episodic, sessions, prefix, nowMs, options);
682
+ } catch {
683
+ return { ...assessed, per_tag_unreadable: true, does_not_block: true, block_enabled: false };
684
+ }
685
+ }
686
+
687
+ async function perTagCurrency(db, assessed, episodic, sessions, prefix, nowMs, options) {
688
+ const tags = writeTagRegistry();
689
+ const hub = hubTag();
690
+ const writeTags = [...new Set([...(hub ? [hub] : []), ...tags])];
691
+ let openRows = [];
692
+ try {
693
+ const cutoff = new Date(nowMs - OPEN_SESSION_LOOKBACK_MS);
694
+ openRows = await db.collection(`${prefix}sessions`).find(
695
+ {
696
+ closed: { $ne: true },
697
+ $or: [
698
+ { updated_at: { $gte: cutoff } },
699
+ { opened_at: { $gte: cutoff } }
700
+ ]
701
+ },
702
+ { projection: { tag: 1, source: 1, channel: 1, opened_at: 1, updated_at: 1, episodic: 1, episodic_id: 1, closed: 1 } }
703
+ ).toArray();
704
+ } catch {
705
+ openRows = [];
706
+ }
707
+ const openSessions = openSessionsFromRows(openRows, nowMs);
708
+ const openIds = new Set();
709
+ for (const row of openRows || []) {
710
+ const id = finiteId(row && row.episodic_id);
711
+ if (id != null) openIds.add(id);
712
+ }
713
+ const { byTag, unattributed } = partitionEpisodic(applyContinuitySourceAlias(episodic), writeTags);
714
+ const per_tag = [];
715
+ for (const tag of writeTags) {
716
+ let doc = null;
717
+ try {
718
+ if (hub && tag === hub) {
719
+ doc = await db.collection('documents').findOne({ doc_id: handoffDoc() });
720
+ } else {
721
+ doc = await db.collection('documents').findOne({ doc_id: `HANDOFF/${tag}.md` });
722
+ if (!doc) doc = await db.collection('documents').findOne({ doc_id: `bots/${tag}/HANDOFF.md` });
723
+ }
724
+ } catch {
725
+ doc = null;
726
+ }
727
+ const one = assessContinuityCurrency({
728
+ handoff: doc && typeof doc.content === 'string' ? {
729
+ doc_id: doc.doc_id, version: doc.version ?? null, sha256: doc.sha256 || null,
730
+ updated_at: doc.updated_at ?? null, content: doc.content
731
+ } : null,
732
+ entries: byTag.get(tag) || [],
733
+ sessions,
734
+ now: options.now,
735
+ blockRequested: false,
736
+ openEpisodicIds: openIds
737
+ });
738
+ per_tag.push({
739
+ tag,
740
+ status: one.status,
741
+ does_not_block: true,
742
+ handoff_doc: doc && doc.doc_id ? doc.doc_id : null,
743
+ cited_episodic_id: one.handoff && one.handoff.cited_episodic_id
744
+ });
745
+ }
746
+ const split = splitUnattributedMaterial(unattributed, nowMs);
747
+ const hours = staleOpenHours();
748
+ const stale_open = openSessions.filter((row) => {
749
+ const since = Date.parse(row.since);
750
+ return Number.isFinite(since) && nowMs - since > hours * 3600000;
751
+ });
752
+ const cutoffMs = epochMs(TAG_ATTRIBUTION_BEGAN);
753
+ const noted = notedLegacyRows(byTag);
754
+ const statuses = [];
755
+ for (const row of per_tag) {
756
+ if (row.status === 'no_handoff' && !tagHasMaterialOnOrAfterCutoff(byTag.get(row.tag), row.tag, nowMs, cutoffMs)) continue;
757
+ statuses.push(row.status);
758
+ }
759
+ if (split.unattributed.length) statuses.push('warn');
760
+ const overall = worstStatus([assessed.status, ...statuses]);
761
+ return {
762
+ ...assessed,
763
+ status: overall,
764
+ per_tag,
765
+ overall_status: overall,
766
+ in_progress: openSessions.map((row) => ({ tag: row.tag, since: row.since, session_id: row.session_id, pointer: false, lag: false })),
767
+ stale_open,
768
+ legacy_pre_attribution: {
769
+ reading: LEGACY_PRE_ATTRIBUTION,
770
+ count: split.legacy.length,
771
+ ids: split.legacy,
772
+ cutoff: TAG_ATTRIBUTION_BEGAN,
773
+ cutoff_basis: LEGACY_CUTOFF_BASIS
774
+ },
775
+ noted_legacy: {
776
+ count: noted.length,
777
+ rows: noted
778
+ },
779
+ unattributed_material: split.unattributed.filter((id) => id != null),
780
+ does_not_block: true,
781
+ block_enabled: false
782
+ };
783
+ }
784
+
785
+ function storedSource(entry) {
786
+ const md = entry && entry.metadata;
787
+ if (md && typeof md === 'object' && typeof md.source === 'string') return md.source.trim();
788
+ if (typeof md === 'string') {
789
+ const match = md.match(/"source"\s*:\s*"([^"]+)"/);
790
+ if (match) return match[1].trim();
791
+ }
792
+ return null;
793
+ }
794
+
795
+ /** A copy of the row with the alias source. The caller's row is left as stored. */
796
+ function aliasEntry(entry, source, alias) {
797
+ const md = entry.metadata;
798
+ if (md && typeof md === 'object') return { ...entry, metadata: { ...md, source: alias } };
799
+ if (typeof md !== 'string') return entry;
800
+ const match = md.match(/"source"\s*:\s*"([^"]+)"/);
801
+ if (!match || match[1].trim() !== source) return entry;
802
+ const at = match.index + match[0].indexOf(match[1]);
803
+ const metadata = md.slice(0, at) + alias + md.slice(at + match[1].length);
804
+ return { ...entry, metadata };
805
+ }
806
+
807
+ function applyContinuitySourceAlias(entries) {
808
+ const out = [];
809
+ for (const entry of entries || []) {
810
+ const source = storedSource(entry);
811
+ const alias = source != null ? CONTINUITY_SOURCE_ALIAS[source] : null;
812
+ out.push(alias ? aliasEntry(entry, source, alias) : entry);
813
+ }
814
+ return out;
815
+ }
816
+
817
+ /**
818
+ * Material rows already split out of the registered write tags.
819
+ * The timestamp is read before the id. A time before TAG_ATTRIBUTION_BEGAN
820
+ * is legacy, and a missing id is still legacy: it is not listed and it does
821
+ * not warn. A missing id at or after the cutoff is pushed as null so the
822
+ * row still warns. A missing timestamp, or one that does not parse, warns.
823
+ */
824
+ export function splitUnattributedMaterial(entries, nowMs = Date.now(), cutoffMs = epochMs(TAG_ATTRIBUTION_BEGAN)) {
825
+ const legacy = [];
826
+ const unattributed = [];
827
+ for (const entry of entries || []) {
828
+ const row = classifyEpisodic(entry, { closeVerification: new Set(), layerTip: new Set() }, nowMs);
829
+ if (!row.material) continue;
830
+ const written = epochMs(entry && entry.timestamp);
831
+ const id = finiteId(entry && entry.id);
832
+ if (cutoffMs != null && written != null && written < cutoffMs) {
833
+ if (id != null) legacy.push(id);
834
+ continue;
835
+ }
836
+ unattributed.push(id);
837
+ }
838
+ return { legacy, unattributed };
839
+ }
840
+
841
+ /**
842
+ * A registered tag has material episodic work that counts toward a missing
843
+ * handoff: a readable time at or after the cutoff, or no readable timestamp.
844
+ */
845
+ function isNotedLegacy(tag, id) {
846
+ return NOTED_LEGACY.some((row) => row.tag === tag && row.id === id);
847
+ }
848
+
849
+ function notedLegacyRows(byTag) {
850
+ const rows = [];
851
+ for (const note of NOTED_LEGACY) {
852
+ const entries = byTag.get(note.tag) || [];
853
+ const present = entries.some((entry) => finiteId(entry && entry.id) === note.id);
854
+ if (present) rows.push({ id: note.id, tag: note.tag, noted: note.noted, reason: note.reason });
855
+ }
856
+ return rows;
857
+ }
858
+
859
+ function tagHasMaterialOnOrAfterCutoff(entries, tag, nowMs, cutoffMs) {
860
+ for (const entry of entries || []) {
861
+ const id = finiteId(entry && entry.id);
862
+ if (id != null && isNotedLegacy(tag, id)) continue;
863
+ const row = classifyEpisodic(entry, { closeVerification: new Set(), layerTip: new Set() }, nowMs);
864
+ if (!row.material) continue;
865
+ const written = epochMs(entry && entry.timestamp);
866
+ if (written == null || cutoffMs == null || written >= cutoffMs) return true;
867
+ }
868
+ return false;
869
+ }