@dreamforgestudiollc/emet 0.3.1 → 0.3.2

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 (71) hide show
  1. package/CHANGELOG.md +29 -0
  2. package/README.md +29 -6
  3. package/docs/BOOTSTRAP.md +2 -0
  4. package/docs/BOTS.md +8 -7
  5. package/docs/DEPLOY.md +6 -0
  6. package/docs/ERROR-CODES-SPEC.md +2 -2
  7. package/docs/ERROR-CODES.md +29 -0
  8. package/docs/GUIDED-SETUP.md +1 -1
  9. package/docs/PERMISSIONS.md +5 -5
  10. package/docs/SETUP.md +10 -4
  11. package/docs/SUBKEYS.md +4 -4
  12. package/package.json +2 -2
  13. package/server.json +8 -4
  14. package/src/aleph.js +34 -13
  15. package/src/annotations.js +6 -2
  16. package/src/approve-throttle.js +3 -0
  17. package/src/atlas-role.js +1 -1
  18. package/src/attribution.js +76 -28
  19. package/src/bound-door.js +170 -0
  20. package/src/break-glass.js +531 -0
  21. package/src/checkpoint.js +241 -0
  22. package/src/chooser.js +543 -0
  23. package/src/claimed-tag.js +140 -0
  24. package/src/conformance.js +269 -5
  25. package/src/deep-links.js +267 -0
  26. package/src/dispatch.js +112 -18
  27. package/src/error-codes.js +29 -0
  28. package/src/error-log.js +138 -26
  29. package/src/error-report.js +17 -5
  30. package/src/gaps.js +1 -1
  31. package/src/grants.js +230 -0
  32. package/src/http-remote.js +80 -26
  33. package/src/index.js +18 -2
  34. package/src/invites.js +47 -1
  35. package/src/layers.js +1 -1
  36. package/src/lessons-to-checks.js +1 -1
  37. package/src/logger.js +3 -1
  38. package/src/oauth-provider.js +89 -5
  39. package/src/owl.js +232 -0
  40. package/src/owner-approvals.js +24 -267
  41. package/src/owner-session.js +174 -0
  42. package/src/pages.js +1 -1
  43. package/src/persons.js +39 -6
  44. package/src/proof-run.js +70 -0
  45. package/src/redact.js +4 -0
  46. package/src/request-log.js +2 -2
  47. package/src/rotate.js +554 -0
  48. package/src/rune-dispatch.js +1 -1
  49. package/src/session-graph.js +44 -25
  50. package/src/session.js +3 -3
  51. package/src/setup.js +21 -12
  52. package/src/staged-write.js +522 -0
  53. package/src/startup-pages.js +2 -2
  54. package/src/startup-payload.js +3 -3
  55. package/src/subkeys.js +61 -0
  56. package/src/tools.js +270 -78
  57. package/src/transcript-session.js +23 -4
  58. package/src/validation.js +1 -1
  59. package/src/version.js +1 -1
  60. package/src/writer-approval.js +394 -0
  61. package/templates/AREA.md +1 -1
  62. package/templates/BOTHANDOFF.md +2 -2
  63. package/templates/GRANT.md +48 -0
  64. package/templates/INDEX.md +9 -7
  65. package/templates/PROCEDURE.md +1 -1
  66. package/templates/ROSTER.md +2 -2
  67. package/templates/SEED.md +2 -2
  68. package/templates/SESSIONDISPOSITION.md +59 -0
  69. package/templates/STAGING.md +1 -1
  70. package/templates/STANDARD.md +1 -1
  71. package/templates/THREAD.md +1 -1
package/src/dispatch.js CHANGED
@@ -9,7 +9,7 @@
9
9
  * Until 2026-09-27 index.js (stdio) and http-remote.js (HTTP) each carried a
10
10
  * full switch mapping tool name to handler. dispatch.test.js compared the two
11
11
  * by case NAME and caught one class of drift (the session_id alias divergence,
12
- * an earlier fix); it could not see argument drift, and the code audit of
12
+ * thatcommit); it could not see argument drift, and the code audit of
13
13
  * 2026-09-27 found one - setupComplete received the logger on stdio and not on
14
14
  * HTTP. A rule stated twice drifts; this file is the one statement.
15
15
  *
@@ -20,8 +20,9 @@
20
20
  import { EmetError, ErrorCodes, StatusCodes } from './database.js';
21
21
  import { ValidationError } from './validation.js';
22
22
  import { registeredSourceTags } from './setup.js';
23
- import { echoId } from './session-graph.js';
23
+ import { echoId, sessionOf } from './session-graph.js';
24
24
  import { currentActor } from './persons.js';
25
+ import { recordError } from './error-log.js';
25
26
  import {
26
27
  initialize, setupStatus, setupComplete, verifyConnection, sessionClose, findGaps, readFloor,
27
28
  handleError, createSuccessResponse,
@@ -32,7 +33,10 @@ import {
32
33
  resolvedSourceTag,
33
34
  TOOLS
34
35
  } from './tools.js';
36
+ import { refuseSophiaDoor, sophiaActor } from './bound-door.js';
37
+ import { beginStagedDoc, appendStagedChunk, commitStagedDoc, abortStagedDoc } from './staged-write.js';
35
38
  import { reserveToolNames } from './rune-registry.js';
39
+ import { applyCheckpoint, checkpointOnError, checkpointStatus } from './checkpoint.js';
36
40
 
37
41
  reserveToolNames([...TOOLS.map((tool) => tool.name), 'emet_subkey_request', 'emet_subkey_claim', 'emet_subkey_revoke', 'emet_subkey_end_session']);
38
42
 
@@ -42,7 +46,7 @@ reserveToolNames([...TOOLS.map((tool) => tool.name), 'emet_subkey_request', 'eme
42
46
  * isError envelope, so the transport's audit line always has an outcome.
43
47
  */
44
48
  /**
45
- * The source tag under one name. `source` is the name on every write (Alex,
49
+ * The source tag under one name. `source` is the name on every write (the owner,
46
50
  * 2026-09-27, code audit 1.5c); the older per-tool names - updated_by,
47
51
  * retired_by, accepted_by on documents, channel on transcripts - are read as
48
52
  * aliases for one release and then dropped. metadata.source on the layers is
@@ -54,11 +58,13 @@ export function sourceOf(args) {
54
58
  // may use the caller's tag only when it is an exact member of EMET_SOURCE_TAGS.
55
59
  // Stdio still reads the argument, and requireRegisteredSource checks the registry.
56
60
  const caller = args.source ?? args.updated_by ?? args.retired_by ?? args.accepted_by ?? args.channel ?? null;
57
- return resolvedSourceTag(caller).tag;
61
+ const decision = resolvedSourceTag(caller);
62
+ if (decision.from === 'bound-door') refuseSophiaDoor(sophiaActor());
63
+ return decision.tag;
58
64
  }
59
65
 
60
66
  /**
61
- * A transcript write names a registered host or is refused (Alex, 2026-09-27,
67
+ * A transcript write names a registered host or is refused (the owner, 2026-09-27,
62
68
  * code audit 1.5d: nine spellings for five hosts in the store). Registered =
63
69
  * EMET_SOURCE_TAGS, exact membership only. With no registry configured, any
64
70
  * non-empty tag passes. A refusal does not publish the registry.
@@ -130,7 +136,7 @@ export async function dispatchTool(name, args, ctx) {
130
136
  // that names a session fails closed when the graph cannot be read.
131
137
  const sg = await import('./session-graph.js');
132
138
  // The exchange number, normalized ONCE, before the graph, the closed-session
133
- // guard and the tool all read it (2026-10-01, the second reader's blocker on an earlier draft: the
139
+ // guard and the tool all read it (2026-10-01, Tester's blocker on thatcommit: the
134
140
  // guard read "4" as 4, the tool did not, so a text "4" was a retry to one and
135
141
  // a new exchange to the other). A whole number, or its text, or absent.
136
142
  if (name === 'emet_transcript_append') {
@@ -183,17 +189,37 @@ export async function dispatchTool(name, args, ctx) {
183
189
  if (grace && grace.grace) args = { ...args, session_id: grace.part, exchange_index: grace.index };
184
190
  // A correction of a closed session: the exchanges with their numbers normalized.
185
191
  if (grace && grace.revise) { args = { ...args, exchanges: grace.exchanges }; grace = null; }
192
+ // After the tool has written. An append that just saved moves session_end
193
+ // to now, so this read sees the checkpoint it cleared. A read failure never
194
+ // fails the call and never claims the save is current.
195
+ const attachCheckpoint = async (data) => {
196
+ try {
197
+ const checkpoint = await checkpointStatus(dbManager, now);
198
+ return applyCheckpoint(data, checkpoint, { always: name === 'emet_status', sessionId: sg.sessionOf(args) });
199
+ } catch {
200
+ const unread = checkpointOnError(name);
201
+ if (unread && data && typeof data === 'object' && !Array.isArray(data)) {
202
+ data.checkpoint = unread;
203
+ return true;
204
+ }
205
+ return false;
206
+ }
207
+ };
208
+ const finish = async (data) => {
209
+ await attachCheckpoint(data);
210
+ return createSuccessResponse(data, name);
211
+ };
186
212
  // A retry of the saved closing exchange is answered here; the tool is NOT
187
- // called, so nothing can be written (the second reader's blocker on an earlier draft).
213
+ // called, so nothing can be written (Tester's blocker on thatcommit).
188
214
  if (grace && grace.retry) {
189
215
  const block = sg.graphBlock(graph);
190
- return createSuccessResponse({
216
+ return finish({
191
217
  session_id: grace.base, exchange_index: grace.index, already_present: true, written: false,
192
218
  closing_exchange: { accepted: true, session: grace.base, exchange_index: grace.index, locked: true, already_saved: true, notice: grace.notice },
193
219
  ...(block ? { session_graph: block } : {})
194
- }, name);
220
+ });
195
221
  }
196
- const ok = (data) => {
222
+ const ok = async (data) => {
197
223
  // A sub-key, claim nonce, or session handle is delivered once by the tool
198
224
  // that minted it. Later receipts do not repeat it.
199
225
  if (data && typeof data === 'object' && !Array.isArray(data)) {
@@ -218,13 +244,13 @@ export async function dispatchTool(name, args, ctx) {
218
244
  if (graph || name === 'emet_session_open') {
219
245
  sg.graphAfter(name, args, data, dbManager, logger, now); // never throws; not awaited
220
246
  }
221
- return createSuccessResponse(data, name);
247
+ return finish(data);
222
248
  };
223
- // The close's state write is awaited (the second reader's nit 6), so an append sent after
249
+ // The close's state write is awaited (Tester's nit 6), so an append sent after
224
250
  // the close returns already finds the session closed - when the write
225
251
  // succeeds. A failed write is retried once; if it still fails the reply
226
252
  // says so (closed_recorded: false, with a warning) instead of reading as a
227
- // locked session (2026-10-01, the second reader's nit 2 on an earlier draft, the reviewer's
253
+ // locked session (2026-10-01, Tester's nit 2 on thatcommit, Reviewer's
228
254
  // condition 2). Every other step is recorded without holding up the reply.
229
255
  const recordClose = async (data) => {
230
256
  let rec = await sg.graphAfter(name, args, data, dbManager, logger, now);
@@ -241,13 +267,24 @@ export async function dispatchTool(name, args, ctx) {
241
267
  if (typeof data.instructions === 'string') data.instructions = `${data.instructions} ${warning}`;
242
268
  }
243
269
  }
244
- return createSuccessResponse(data, name);
270
+ return finish(data);
245
271
  };
246
272
  switch (name) {
247
273
  case 'emet_initialize': return ok(await initialize(args, { onLate: (late) => sg.recordLatePages(late, dbManager, logger) }));
248
274
  case 'emet_setup_complete': return ok(await setupComplete(args.answers || {}, logger, { reissue: args.reissue === true, source: sourceOf(args) }));
249
275
  case 'emet_session_close': {
250
276
  const data = await sessionClose(args);
277
+ // Blocked and escalated closes return a result, not a thrown error.
278
+ // The log row still names the session. A thrown refusal is logged in
279
+ // the catch below. A complete close is not an error.
280
+ if (data && (data.state === 'blocked' || data.state === 'escalate')) {
281
+ void recordError({
282
+ emet_code: data.state === 'escalate' ? 'EMET-SESS-007' : 'EMET-SESS-006',
283
+ class_code: ErrorCodes.VALIDATION_ERROR,
284
+ tool: 'emet_session_close',
285
+ session_id: sessionOf(args) || ''
286
+ });
287
+ }
251
288
  try {
252
289
  const { setting } = await import('./env.js');
253
290
  if (data && data.state === 'complete' && setting('SUBKEYS') === '1') {
@@ -290,9 +327,19 @@ export async function dispatchTool(name, args, ctx) {
290
327
  const { approvalsDeps, sourceRegistry } = await import('./tools.js');
291
328
  const ownerId = await resolveTokenSubject(dbManager.db).catch(() => null);
292
329
  try {
330
+ if (args && args.decision === 'prepare') {
331
+ const { prepareWriterRequest } = await import('./writer-approval.js');
332
+ const { COLLECTION_PREFIX } = await import('./database.js');
333
+ const fields = { ...(args || {}) };
334
+ if (!fields.claimed_tag && typeof args.tag === 'string') fields.claimed_tag = args.tag;
335
+ return ok(await prepareWriterRequest(dbManager.db, COLLECTION_PREFIX, rawActor(), fields));
336
+ }
293
337
  return ok(await att.clientApprove(approvalsDeps, rawActor(), ownerId, args, sourceRegistry()));
294
338
  } catch (e) {
295
- if (e && e.attributionRefusal) throw new ValidationError('tag', e.message, { code: 'EMET-TOOL-007' });
339
+ if (e && e.attributionRefusal) {
340
+ if (args && args.decision === 'prepare') throw new ValidationError('tag', e.message, { code: 'EMET-AUTH-043' });
341
+ throw new ValidationError('tag', e.message, { code: 'EMET-TOOL-007' });
342
+ }
296
343
  throw e;
297
344
  }
298
345
  }
@@ -300,7 +347,7 @@ export async function dispatchTool(name, args, ctx) {
300
347
  case 'recall': return ok(await recallMemories(dbManager, args.query, args.layer || null, args.limit || 10, logger, AuditOperation, { history: args.history === true, order: args.order }));
301
348
  case 'query_layer': return ok(await queryLayer(dbManager, args.layer, args.options || {}, logger, AuditOperation));
302
349
  case 'emet_status': {
303
- // One diagnostic (2026-09-27, Alex: one tool with several functions over
350
+ // One diagnostic (2026-09-27, the owner: one tool with several functions over
304
351
  // several overlapping ones). setupStatus + the per-layer counts, and the
305
352
  // write-path probe on request.
306
353
  const status = await setupStatus();
@@ -330,6 +377,36 @@ export async function dispatchTool(name, args, ctx) {
330
377
  Object.assign(status, callerAttribution());
331
378
  const v = att.approvalsView(att.cachedApprovals(), rawActor() || { transport: 'stdio' }, null);
332
379
  if (v) status.client_approvals = v;
380
+ const { claimedTagTraffic } = await import('./claimed-tag.js');
381
+ status.claimed_tag_traffic = claimedTagTraffic();
382
+ const { breakGlassMetric } = await import('./deep-links.js');
383
+ status.break_glass = breakGlassMetric();
384
+ const { rotateMetric } = await import('./rotate.js');
385
+ status.rotate_all = rotateMetric();
386
+ const { writerApprovalMetric } = await import('./writer-approval.js');
387
+ status.writer_approval = writerApprovalMetric();
388
+ const { owlRetirementMetric } = await import('./owl.js');
389
+ status.owl_retirement = owlRetirementMetric();
390
+ const { proofRunMetric } = await import('./proof-run.js');
391
+ status.proof_run = proofRunMetric();
392
+ if (args.session_id !== undefined && args.session_id !== null && args.session_id !== '') {
393
+ if (typeof args.session_id !== 'string') {
394
+ throw new ValidationError('session_id', 'must be a string', { code: 'EMET-SESS-004' });
395
+ }
396
+ const asked = args.session_id.trim();
397
+ if (asked) {
398
+ try {
399
+ const base = sg.baseOf(asked);
400
+ const found = await sg.sessionStatus(base, dbManager);
401
+ status.session = {
402
+ session_id: base,
403
+ state: !found.exists ? 'absent' : (found.closed ? 'closed' : 'open')
404
+ };
405
+ } catch {
406
+ status.session = { state: 'unreadable', emet_code: 'EMET-SESS-005' };
407
+ }
408
+ }
409
+ }
333
410
  if (setting('SUBKEYS') === '1') {
334
411
  const sk = await import('./subkeys.js');
335
412
  const { approvalsDeps } = await import('./tools.js');
@@ -350,6 +427,10 @@ export async function dispatchTool(name, args, ctx) {
350
427
  case 'read_doc': return ok(await readDoc(args.doc_id, logger, { offset: args.offset ?? 0, limit: args.limit ?? READ_DOC_PAGE_DEFAULT, expected_version: args.expected_version, expected_sha256: args.expected_sha256 }));
351
428
  case 'read_doc_history': return ok(await readDocHistory(args.doc_id, args.version ?? null, logger));
352
429
  case 'write_doc': return ok(await writeDoc(args.doc_id, args.content, sourceOf(args), null, logger, { supersedes: args.supersedes ?? null, reason: args.reason || null, session_id: args.session_id || null }));
430
+ case 'write_doc_begin': return ok(await beginStagedDoc({ doc_id: args.doc_id, source: sourceOf(args), session_id: args.session_id || null, supersedes: args.supersedes ?? null, reason: args.reason || null }, logger, now));
431
+ case 'write_doc_append': return ok(await appendStagedChunk({ stage_id: args.stage_id, part: args.part, chunk: args.chunk, source: sourceOf(args), session_id: args.session_id || null }, logger, now));
432
+ case 'write_doc_commit': return ok(await commitStagedDoc({ stage_id: args.stage_id, doc_id: args.doc_id, sha256: args.sha256, part_count: args.part_count, source: sourceOf(args), session_id: args.session_id || null, supersedes: args.supersedes ?? null, reason: args.reason || null }, logger, now));
433
+ case 'write_doc_abort': return ok(await abortStagedDoc({ stage_id: args.stage_id, source: sourceOf(args), session_id: args.session_id || null }, logger, now));
353
434
  case 'list_docs': return ok(await listDocs(args.prefix || null, logger, args.include_retired === true));
354
435
  case 'retire_doc': return ok(await retireDoc(args.doc_id, args.reason || null, sourceOf(args), logger, { session_id: args.session_id || null }));
355
436
  case 'rename_doc': return ok(await renameDoc(args.old_id, args.new_id, sourceOf(args), logger, args.reason || null, { session_id: args.session_id || null }));
@@ -383,7 +464,20 @@ export async function dispatchTool(name, args, ctx) {
383
464
  }
384
465
  const { serveRune } = await import('./rune-dispatch.js');
385
466
  const ran = await serveRune(name, args, { logger, AuditOperation, dbManager });
386
- if (ran) return ran;
467
+ if (ran) {
468
+ // serveRune builds its own success envelope. Stamp the reminder on
469
+ // that payload when the call names a due session. A failed read does
470
+ // not fail the serve and does not claim the save is current.
471
+ if (!ran.isError && ran.content && ran.content[0] && typeof ran.content[0].text === 'string') {
472
+ try {
473
+ const body = JSON.parse(ran.content[0].text);
474
+ if (body && body.success === true && body.data && typeof body.data === 'object' && !Array.isArray(body.data)) {
475
+ if (await attachCheckpoint(body.data)) ran.content[0].text = JSON.stringify(body);
476
+ }
477
+ } catch { /* the reminder never fails the serve */ }
478
+ }
479
+ return ran;
480
+ }
387
481
  throw new EmetError(`Unknown tool: ${name}`, ErrorCodes.UNKNOWN_TOOL, StatusCodes.BAD_REQUEST, { code: 'EMET-TOOL-008' });
388
482
  }
389
483
  }
@@ -392,7 +486,7 @@ export async function dispatchTool(name, args, ctx) {
392
486
  try { const sg = await import('./session-graph.js'); await sg.markCloseGrace(grace.base, dbManager, { release: true }); }
393
487
  catch (e) { logger?.warn?.('closing exchange: claim not released', { error: e && e.message }); }
394
488
  }
395
- return handleError(error, name, logger);
489
+ return handleError(error, name, logger, name === 'emet_session_close' ? { session_id: sessionOf(args || {}) } : null);
396
490
  }
397
491
  }
398
492
 
@@ -74,6 +74,11 @@ export const ERROR_CODES = Object.freeze({
74
74
  'EMET-AUTH-037': Object.freeze({ area: 'AUTH', summary: "Only the owner can create member access", status: 'active', internal: false }),
75
75
  'EMET-AUTH-038': Object.freeze({ area: 'AUTH', summary: "The error report is owner-only", status: 'active', internal: false }),
76
76
  'EMET-AUTH-039': Object.freeze({ area: 'AUTH', summary: "HTTP attribution preflight was refused", status: 'active', internal: false }),
77
+ 'EMET-AUTH-040': Object.freeze({ area: 'AUTH', summary: "A claimed source tag cannot write after the kill date", status: 'active', internal: false }),
78
+ 'EMET-AUTH-041': Object.freeze({ area: 'AUTH', summary: "A credential was revoked by rotation", status: 'active', internal: false }),
79
+ 'EMET-AUTH-042': Object.freeze({ area: 'AUTH', summary: "A retired owl credential was refused", status: 'active', internal: false }),
80
+ 'EMET-AUTH-043': Object.freeze({ area: 'AUTH', summary: "A writer approval step was refused", status: 'active', internal: false }),
81
+ 'EMET-AUTH-044': Object.freeze({ area: 'AUTH', summary: "A bound login cannot stamp another tag", status: 'active', internal: false }),
77
82
  'EMET-CFG-001': Object.freeze({ area: 'CFG', summary: "Database name must be a plain name", status: 'active', internal: true }),
78
83
  'EMET-CFG-002': Object.freeze({ area: 'CFG', summary: "Collection prefix must be a plain name", status: 'active', internal: true }),
79
84
  'EMET-CFG-004': Object.freeze({ area: 'CFG', summary: "Hosted setup cannot turn sub-keys on from here", status: 'active', internal: false }),
@@ -120,6 +125,7 @@ export const ERROR_CODES = Object.freeze({
120
125
  'EMET-DB-034': Object.freeze({ area: 'DB', summary: "Failed to patch a document", status: 'active', internal: false }),
121
126
  'EMET-DB-035': Object.freeze({ area: 'DB', summary: "Failed semantic recall", status: 'active', internal: false }),
122
127
  'EMET-DB-036': Object.freeze({ area: 'DB', summary: "Failed corpus recall", status: 'active', internal: false }),
128
+ 'EMET-DB-037': Object.freeze({ area: 'DB', summary: "Failed to stage a document write", status: 'active', internal: false }),
123
129
  'EMET-DOC-001': Object.freeze({ area: 'DOC', summary: "doc_id must be a non-empty string", status: 'active', internal: false }),
124
130
  'EMET-DOC-002': Object.freeze({ area: 'DOC', summary: "Document not found", status: 'active', internal: false }),
125
131
  'EMET-DOC-003': Object.freeze({ area: 'DOC', summary: "No retained revision", status: 'active', internal: false }),
@@ -179,6 +185,27 @@ export const ERROR_CODES = Object.freeze({
179
185
  'EMET-DOC-057': Object.freeze({ area: 'DOC', summary: "old_str must be a non-empty string", status: 'active', internal: false }),
180
186
  'EMET-DOC-058': Object.freeze({ area: 'DOC', summary: "new_str must be a string", status: 'active', internal: false }),
181
187
  'EMET-DOC-059': Object.freeze({ area: 'DOC', summary: "Patch edits overlap", status: 'active', internal: false }),
188
+ 'EMET-DOC-060': Object.freeze({ area: 'DOC', summary: "Stage not found for this writer", status: 'active', internal: false }),
189
+ 'EMET-DOC-061': Object.freeze({ area: 'DOC', summary: "Stage has expired", status: 'active', internal: false }),
190
+ 'EMET-DOC-062': Object.freeze({ area: 'DOC', summary: "Stage was aborted", status: 'active', internal: false }),
191
+ 'EMET-DOC-063': Object.freeze({ area: 'DOC', summary: "Stage is already committed", status: 'active', internal: false }),
192
+ 'EMET-DOC-064': Object.freeze({ area: 'DOC', summary: "A staged chunk exceeds the part limit", status: 'active', internal: false }),
193
+ 'EMET-DOC-065': Object.freeze({ area: 'DOC', summary: "A staged append is out of order", status: 'active', internal: false }),
194
+ 'EMET-DOC-066': Object.freeze({ area: 'DOC', summary: "A staged part was already stored with different bytes", status: 'active', internal: false }),
195
+ 'EMET-DOC-067': Object.freeze({ area: 'DOC', summary: "Staged content would exceed the 2MB limit", status: 'active', internal: false }),
196
+ 'EMET-DOC-068': Object.freeze({ area: 'DOC', summary: "A staged write has too many parts", status: 'active', internal: false }),
197
+ 'EMET-DOC-069': Object.freeze({ area: 'DOC', summary: "Commit digest does not match the assembled content", status: 'active', internal: false }),
198
+ 'EMET-DOC-070': Object.freeze({ area: 'DOC', summary: "Commit part count does not match the stage", status: 'active', internal: false }),
199
+ 'EMET-DOC-071': Object.freeze({ area: 'DOC', summary: "A staged chunk must be a non-empty string", status: 'active', internal: false }),
200
+ 'EMET-DOC-072': Object.freeze({ area: 'DOC', summary: "A staged part index must be a whole number", status: 'active', internal: false }),
201
+ 'EMET-DOC-073': Object.freeze({ area: 'DOC', summary: "Commit sha256 must be a hex digest", status: 'active', internal: false }),
202
+ 'EMET-DOC-074': Object.freeze({ area: 'DOC', summary: "Too many open stages for this writer", status: 'active', internal: false }),
203
+ 'EMET-DOC-075': Object.freeze({ area: 'DOC', summary: "Commit names a different document than the stage", status: 'active', internal: false }),
204
+ 'EMET-DOC-076': Object.freeze({ area: 'DOC', summary: "This stage is already being committed", status: 'active', internal: false }),
205
+ 'EMET-DOC-077': Object.freeze({ area: 'DOC', summary: "Commit supersedes does not match the stage", status: 'active', internal: false }),
206
+ 'EMET-DOC-078': Object.freeze({ area: 'DOC', summary: "Commit reason does not match the stage", status: 'active', internal: false }),
207
+ 'EMET-DOC-079': Object.freeze({ area: 'DOC', summary: "This call's source does not match the stage", status: 'active', internal: false }),
208
+ 'EMET-DOC-080': Object.freeze({ area: 'DOC', summary: "This call's session does not match the stage", status: 'active', internal: false }),
182
209
  'EMET-GEM-001': Object.freeze({ area: 'GEM', summary: "Read-back found no document", status: 'active', internal: false }),
183
210
  'EMET-GEM-002': Object.freeze({ area: 'GEM', summary: "Read-back content digest differs", status: 'active', internal: false }),
184
211
  'EMET-GEM-003': Object.freeze({ area: 'GEM', summary: "Read-back version differs", status: 'active', internal: false }),
@@ -277,6 +304,8 @@ export const ERROR_CODES = Object.freeze({
277
304
  'EMET-SESS-003': Object.freeze({ area: 'SESS', summary: "timestamp_start must be before timestamp_end", status: 'active', internal: false }),
278
305
  'EMET-SESS-004': Object.freeze({ area: 'SESS', summary: "session_id must be a string", status: 'active', internal: false }),
279
306
  'EMET-SESS-005': Object.freeze({ area: 'SESS', summary: "Session graph is unavailable", status: 'active', internal: false }),
307
+ 'EMET-SESS-006': Object.freeze({ area: 'SESS', summary: "Session close was blocked", status: 'active', internal: false }),
308
+ 'EMET-SESS-007': Object.freeze({ area: 'SESS', summary: "Session close escalated", status: 'active', internal: false }),
280
309
  'EMET-TOOL-001': Object.freeze({ area: 'TOOL', summary: "A tool has no annotation entry", status: 'active', internal: true }),
281
310
  'EMET-TOOL-002': Object.freeze({ area: 'TOOL', summary: "A source tag is required", status: 'active', internal: false }),
282
311
  'EMET-TOOL-003': Object.freeze({ area: 'TOOL', summary: "A source tag is required and none are registered", status: 'active', internal: false }),
package/src/error-log.js CHANGED
@@ -1,13 +1,22 @@
1
1
  /**
2
2
  * Operational error log. Not a controlled document and not a memory.
3
3
  * Entries are capped and rotated. Nothing here stores message text,
4
- * arguments, document ids, names, or secrets.
4
+ * arguments, document ids, or secrets. client_id and grant_id are
5
+ * the caller's credential ids (a registration id or metadata URL, and the
6
+ * token family). A value that is not that shape is stored as unknown or none.
7
+ * A refused or failed emet_session_close also stores session_id when it is a
8
+ * minted session id (YYYY-MM-DD_slug, optional -N through -99, optional
9
+ * _verbatim_partN). A bearer, a JWT, a URI, or any other shape is unknown.
10
+ * Every other row stores none. A caller-supplied session id on any other
11
+ * tool is not stored.
12
+ * A daily summary keeps client_id with the count when its index can.
5
13
  */
6
14
 
7
15
  import { readySharedClient } from './mongo-connect.js';
8
- import { MONGODB_URI, MONGODB_DB, ErrorCodes } from './database.js';
16
+ import { MONGODB_DB, ErrorCodes } from './database.js';
9
17
  import { redactText } from './redact.js';
10
18
  import { currentActor, getPerson } from './persons.js';
19
+ import { logClientId, logDoor, logGrantId } from './grants.js';
11
20
  import { registeredSourceTags } from './setup.js';
12
21
  import { EMET_VERSION } from './version.js';
13
22
  import { CodedError, EMET_CODE_RE, EMET_INT_001, lookupEmetCode, newCorrelationId } from './error-codes.js';
@@ -18,20 +27,40 @@ export const ERROR_LOG_MAX = 10000;
18
27
  export const ERROR_LOG_DAYS = 90;
19
28
 
20
29
  const ENTRY_KEYS = Object.freeze([
21
- '_id', 't', 'emet_code', 'class_code', 'tool', 'version', 'transport', 'caller', 'role', 'correlation_id', 'count'
30
+ '_id', 't', 'emet_code', 'class_code', 'tool', 'version', 'transport', 'caller', 'role',
31
+ 'client_id', 'grant_id', 'door', 'session_id', 'correlation_id', 'count'
22
32
  ]);
23
- const SUMMARY_KEYS = Object.freeze(['day', 'emet_code', 'tool', 'version', 'count']);
33
+ // Minted by sessionBaseId / firstUnclosedBase / partId only:
34
+ // YYYY-MM-DD_slug[-N][_verbatim_partN]
35
+ // The slug is lowercase, hyphens only between alphanumerics, at most 40
36
+ // characters, or 43 when a closed base is reopened as -2..-99. A bearer
37
+ // (ghp_, sk-), a JWT, a URI, a space, or any other shape is unknown.
38
+ // redactText leaves ghp_ and sk- unchanged, and a JWT whose signature is
39
+ // shorter than 8 characters, so the grammar is the guard, not the scrub.
40
+ const SESSION_ID_RE = /^([0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01]))_([a-z0-9]+(?:-[a-z0-9]+)*)(?:_verbatim_part([1-9][0-9]{0,3}))?$/;
41
+ const SESSION_SLUG_MAX = 43;
42
+ const SUMMARY_KEYS = Object.freeze(['day', 'emet_code', 'tool', 'version', 'client_id', 'count']);
24
43
  const CLASS_CODES = new Set(Object.values(ErrorCodes));
25
44
 
26
45
  let backend = null;
27
46
  let indexed = false;
28
47
  let chain = Promise.resolve();
48
+ // False when an older unique summary index cannot be replaced. The server
49
+ // role may create indexes and may not drop them. Rotation then keeps the
50
+ // old counts and does not invent a client on a shared summary row.
51
+ let summaryKeepsClient = true;
29
52
 
30
53
  /** Test seam. Pass null to use Mongo again. */
31
54
  export function setErrorLogBackend(store) {
32
55
  backend = store;
33
56
  }
34
57
 
58
+ /** Test seam. The summary index decision is once per process. */
59
+ export function _resetErrorLogForTests() {
60
+ indexed = false;
61
+ summaryKeepsClient = true;
62
+ }
63
+
35
64
  export function useMemoryErrorLog() {
36
65
  const store = { entries: [], summaries: [], fail: false };
37
66
  backend = store;
@@ -62,11 +91,21 @@ function safeCorrelation(id) {
62
91
  return typeof id === 'string' && /^[0-9a-f]{16}$/.test(id) ? id : newCorrelationId();
63
92
  }
64
93
 
65
- function callerTag() {
94
+ /** Log-safe session id. Only a minted YYYY-MM-DD_slug[-N][_verbatim_partN] is kept. */
95
+ export function logSessionId(id) {
96
+ if (typeof id !== 'string') return 'unknown';
97
+ const trimmed = id.trim();
98
+ const match = SESSION_ID_RE.exec(trimmed);
99
+ if (!match || match[2].length > SESSION_SLUG_MAX) return 'unknown';
100
+ const clean = scrub(trimmed);
101
+ return clean === trimmed ? trimmed : 'unknown';
102
+ }
103
+
104
+ function callerTag(actor) {
66
105
  let raw = null;
67
106
  try {
68
- const actor = currentActor();
69
- if (actor && typeof actor.sourceTag === 'string' && actor.sourceTag) raw = actor.sourceTag;
107
+ const who = actor || currentActor();
108
+ if (who && typeof who.sourceTag === 'string' && who.sourceTag) raw = who.sourceTag;
70
109
  } catch { raw = null; }
71
110
  const tags = registeredSourceTags();
72
111
  if (typeof raw !== 'string' || !tags.includes(raw)) return 'unregistered';
@@ -75,29 +114,72 @@ function callerTag() {
75
114
  return raw;
76
115
  }
77
116
 
78
- async function roleOf(db) {
117
+ async function roleOf(db, actor) {
79
118
  try {
80
- const actor = currentActor();
81
- if (actor.transport === 'stdio') return 'owner';
82
- if (actor.transport !== 'http' || !actor.personId || !db) return 'guest';
83
- const person = await getPerson(db, actor.personId);
119
+ const who = actor || currentActor();
120
+ if (who.transport === 'stdio') return 'owner';
121
+ if (who.transport !== 'http' || !who.personId || !db) return 'guest';
122
+ const person = await getPerson(db, who.personId);
84
123
  return person && person.role === 'owner' ? 'owner' : 'guest';
85
124
  } catch {
86
125
  return 'guest';
87
126
  }
88
127
  }
89
128
 
129
+ /** Credential for the log. Stdio with no client id is the local client. logClientId turns anything else missing or unrecognised into unknown. */
130
+ function clientIdForLog(actor) {
131
+ if (actor && typeof actor.clientId === 'string' && actor.clientId) return actor.clientId;
132
+ if (actor && actor.transport === 'stdio') return 'stdio';
133
+ return null;
134
+ }
135
+
136
+ /** The pre-client_id unique summary index: day, code, tool, version. A client_id key is the new index. */
137
+ function legacySummaryIndex(indexes) {
138
+ return (indexes || []).find((idx) => {
139
+ const key = idx && idx.key;
140
+ if (!idx || idx.unique !== true || !key) return false;
141
+ const names = Object.keys(key);
142
+ return names.length === 4 && key.day === 1 && key.emet_code === 1 && key.tool === 1 && key.version === 1;
143
+ });
144
+ }
145
+
146
+ async function ensureSummaryIndex(db) {
147
+ const summary = db.collection(ERROR_LOG_SUMMARY_COLLECTION);
148
+ let indexes = [];
149
+ try { indexes = await summary.indexes(); } catch { indexes = []; }
150
+ const legacy = legacySummaryIndex(indexes);
151
+ if (legacy) {
152
+ if (!legacy.name) summaryKeepsClient = false;
153
+ else {
154
+ try { await summary.dropIndex(legacy.name); }
155
+ catch { summaryKeepsClient = false; }
156
+ }
157
+ }
158
+ if (!summaryKeepsClient) return;
159
+ await summary.createIndex(
160
+ { day: 1, emet_code: 1, tool: 1, version: 1, client_id: 1 },
161
+ { unique: true }
162
+ );
163
+ }
164
+
90
165
  function buildEntry(fields) {
166
+ const tool = safeTool(fields.tool);
91
167
  const doc = {
92
168
  _id: fields._id || newCorrelationId(),
93
169
  t: typeof fields.t === 'string' && fields.t ? fields.t : new Date().toISOString(),
94
170
  emet_code: safeCode(fields.emet_code),
95
171
  class_code: safeClass(fields.class_code),
96
- tool: safeTool(fields.tool),
172
+ tool,
97
173
  version: EMET_VERSION,
98
174
  transport: fields.transport === 'http' ? 'http' : 'stdio',
99
175
  caller: fields.caller === 'unregistered' || typeof fields.caller !== 'string' ? 'unregistered' : (scrub(fields.caller) === fields.caller ? fields.caller : 'unregistered'),
100
176
  role: fields.role === 'owner' ? 'owner' : 'guest',
177
+ client_id: logClientId(fields.client_id),
178
+ grant_id: logGrantId(fields.grant_id),
179
+ door: logDoor(fields.door),
180
+ // Only a session-close row carries a session id. Other tools stay none,
181
+ // even when the caller put a session id on the input.
182
+ session_id: tool === 'emet_session_close' ? logSessionId(fields.session_id) : 'none',
101
183
  correlation_id: safeCorrelation(fields.correlation_id),
102
184
  count: 1
103
185
  };
@@ -107,8 +189,9 @@ function buildEntry(fields) {
107
189
  }
108
190
 
109
191
  function dbHandle() {
110
- if (!MONGODB_URI) return null;
111
192
  const client = readySharedClient();
193
+ // No open client means there is no log database. A URI with no client yet
194
+ // is the same. A client already bound (including a test double) is the store.
112
195
  if (!client) return null;
113
196
  return client.db(MONGODB_DB);
114
197
  }
@@ -122,10 +205,7 @@ async function logCollection() {
122
205
  await col.createIndex({ t: -1 });
123
206
  await col.createIndex({ emet_code: 1, t: -1 });
124
207
  await col.createIndex({ correlation_id: 1 }, { unique: true });
125
- await db.collection(ERROR_LOG_SUMMARY_COLLECTION).createIndex(
126
- { day: 1, emet_code: 1, tool: 1, version: 1 },
127
- { unique: true }
128
- );
208
+ await ensureSummaryIndex(db);
129
209
  }
130
210
  return col;
131
211
  }
@@ -149,21 +229,33 @@ export async function upsertErrorSummary(row) {
149
229
  emet_code: safeCode(row.emet_code),
150
230
  tool: safeTool(row.tool),
151
231
  version: typeof row.version === 'string' ? row.version : EMET_VERSION,
232
+ client_id: logClientId(row.client_id),
152
233
  count: Number(row.count) || 0
153
234
  };
154
235
  const stored = {};
155
236
  for (const key of SUMMARY_KEYS) stored[key] = summary[key];
156
237
  if (backend) {
157
238
  if (backend.fail) throw new CodedError('error log down', { code: 'EMET-INT-001' });
158
- const found = backend.summaries.find((s) => s.day === stored.day && s.emet_code === stored.emet_code && s.tool === stored.tool && s.version === stored.version);
239
+ const found = backend.summaries.find((s) => s.day === stored.day && s.emet_code === stored.emet_code && s.tool === stored.tool && s.version === stored.version && s.client_id === stored.client_id);
159
240
  if (found) found.count += stored.count;
160
241
  else backend.summaries.push({ ...stored });
161
242
  return stored;
162
243
  }
163
244
  const db = await dbHandle();
164
245
  if (!db) return stored;
246
+ // Decide the summary index before the first upsert. A rotation can be the
247
+ // process's first write, and the old unique index must not be asked to
248
+ // hold one row per client until we know whether it can be replaced.
249
+ if (!indexed) await logCollection();
250
+ const filter = {
251
+ day: stored.day,
252
+ emet_code: stored.emet_code,
253
+ tool: stored.tool,
254
+ version: stored.version
255
+ };
256
+ if (summaryKeepsClient) filter.client_id = stored.client_id;
165
257
  await db.collection(ERROR_LOG_SUMMARY_COLLECTION).updateOne(
166
- { day: stored.day, emet_code: stored.emet_code, tool: stored.tool, version: stored.version },
258
+ filter,
167
259
  { $inc: { count: stored.count } },
168
260
  { upsert: true }
169
261
  );
@@ -174,7 +266,7 @@ async function loadRows() {
174
266
  if (backend) return backend.entries.map((row) => ({ ...row }));
175
267
  const col = await logCollection();
176
268
  if (!col) return [];
177
- return col.find({}, { projection: { t: 1, emet_code: 1, tool: 1, version: 1, count: 1 } }).toArray();
269
+ return col.find({}, { projection: { t: 1, emet_code: 1, tool: 1, version: 1, client_id: 1, count: 1 } }).toArray();
178
270
  }
179
271
 
180
272
  export async function rotateErrorLog(options = {}) {
@@ -195,12 +287,14 @@ export async function rotateErrorLog(options = {}) {
195
287
  }
196
288
  const groups = new Map();
197
289
  for (const row of removed) {
198
- const key = `${String(row.t).slice(0, 10)}\0${row.emet_code}\0${row.tool}\0${row.version}`;
290
+ const client_id = logClientId(row.client_id);
291
+ const key = `${String(row.t).slice(0, 10)}\0${row.emet_code}\0${row.tool}\0${row.version}\0${client_id}`;
199
292
  const group = groups.get(key) || {
200
293
  day: String(row.t).slice(0, 10),
201
294
  emet_code: row.emet_code,
202
295
  tool: row.tool,
203
296
  version: row.version,
297
+ client_id,
204
298
  count: 0
205
299
  };
206
300
  group.count += Number(row.count) || 1;
@@ -239,19 +333,37 @@ export async function queryErrorLog({ since, correlation_id, codes } = {}) {
239
333
  }
240
334
 
241
335
  export async function recordError(input = {}) {
336
+ // Read the credential now. The write itself may await, and the row has to
337
+ // name the client that was refused, not whoever is current when it lands.
338
+ // A client_id on the input is not read.
339
+ const actor = currentActor();
340
+ const client_id = clientIdForLog(actor);
341
+ const grant_id = actor.grantId ? actor.grantId : 'unknown';
342
+ const transport = actor.transport === 'http' ? 'http' : 'stdio';
343
+ const caller = callerTag(actor);
344
+ // Stdio is an explicit transport. No actor, or a null transport, is not
345
+ // that door: an error raised outside actorStore.run must not be logged
346
+ // as stdio. logDoor stores anything else as `unknown`.
347
+ const door = actor.transport === 'http' ? actor.door : (actor.transport === 'stdio' ? 'stdio' : 'unknown');
242
348
  const job = (async () => {
243
349
  try {
244
350
  const db = backend ? null : await dbHandle();
245
- const actor = currentActor();
246
351
  await insertErrorLog({
247
352
  t: new Date().toISOString(),
248
353
  emet_code: input.emet_code,
249
354
  class_code: input.class_code,
250
355
  tool: input.tool,
251
356
  correlation_id: input.correlation_id,
252
- transport: actor.transport === 'http' ? 'http' : 'stdio',
253
- caller: callerTag(),
254
- role: await roleOf(db)
357
+ transport,
358
+ caller,
359
+ role: await roleOf(db, actor),
360
+ client_id,
361
+ // A missing door grant is the string `unknown`. buildEntry runs that
362
+ // value through logGrantId, which keeps `unknown` and turns a bearer into `none`.
363
+ grant_id,
364
+ door,
365
+ // Read only for emet_session_close. buildEntry drops it on every other tool.
366
+ session_id: input.session_id
255
367
  });
256
368
  } catch {
257
369
  console.error('error log write failed');