@dreamforgestudiollc/emet 0.3.1 → 0.3.3

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 (72) hide show
  1. package/CHANGELOG.md +40 -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/carry-forward-close.js +386 -0
  22. package/src/checkpoint.js +241 -0
  23. package/src/chooser.js +543 -0
  24. package/src/claimed-tag.js +140 -0
  25. package/src/conformance.js +269 -5
  26. package/src/deep-links.js +267 -0
  27. package/src/dispatch.js +112 -18
  28. package/src/error-codes.js +29 -0
  29. package/src/error-log.js +138 -26
  30. package/src/error-report.js +17 -5
  31. package/src/gaps.js +1 -1
  32. package/src/grants.js +230 -0
  33. package/src/http-remote.js +80 -26
  34. package/src/index.js +18 -2
  35. package/src/invites.js +47 -1
  36. package/src/layers.js +1 -1
  37. package/src/lessons-to-checks.js +1 -1
  38. package/src/logger.js +3 -1
  39. package/src/oauth-provider.js +89 -5
  40. package/src/owl.js +232 -0
  41. package/src/owner-approvals.js +24 -267
  42. package/src/owner-session.js +235 -0
  43. package/src/pages.js +1 -1
  44. package/src/persons.js +39 -6
  45. package/src/proof-run.js +70 -0
  46. package/src/redact.js +4 -0
  47. package/src/request-log.js +2 -2
  48. package/src/rotate.js +554 -0
  49. package/src/rune-dispatch.js +1 -1
  50. package/src/session-graph.js +44 -25
  51. package/src/session.js +52 -9
  52. package/src/setup.js +21 -12
  53. package/src/staged-write.js +522 -0
  54. package/src/startup-pages.js +2 -2
  55. package/src/startup-payload.js +3 -3
  56. package/src/subkeys.js +61 -0
  57. package/src/tools.js +290 -79
  58. package/src/transcript-session.js +23 -4
  59. package/src/validation.js +1 -1
  60. package/src/version.js +1 -1
  61. package/src/writer-approval.js +394 -0
  62. package/templates/AREA.md +1 -1
  63. package/templates/BOTHANDOFF.md +2 -2
  64. package/templates/GRANT.md +48 -0
  65. package/templates/INDEX.md +9 -7
  66. package/templates/PROCEDURE.md +1 -1
  67. package/templates/ROSTER.md +2 -2
  68. package/templates/SEED.md +2 -2
  69. package/templates/SESSIONDISPOSITION.md +59 -0
  70. package/templates/STAGING.md +1 -1
  71. package/templates/STANDARD.md +1 -1
  72. package/templates/THREAD.md +1 -1
@@ -0,0 +1,522 @@
1
+ /**
2
+ * EMET - staged multi-part document write.
3
+ *
4
+ * A host that truncates a large tool argument cannot send a whole record in
5
+ * one write_doc call. This file holds the parts, in order, in
6
+ * `<prefix>doc_stages`. That collection is bookkeeping, not a document and
7
+ * not a memory layer: a read token cannot read it through read_doc, and a
8
+ * chunk is not a revision.
9
+ *
10
+ * commit assembles the parts, checks the caller's sha256 of that exact text,
11
+ * and then calls writeDoc once. Versioning, the prior-copy archive, redaction,
12
+ * the size floors, and the read-back all stay on that one door. An aborted,
13
+ * incomplete, or expired stage leaves the current document untouched.
14
+ *
15
+ * Rows are updated in place (open, committing, committed, aborted, expired).
16
+ * Nothing in this file is deleted.
17
+ */
18
+
19
+ import { randomBytes, timingSafeEqual } from 'node:crypto';
20
+ import { connectMongo } from './mongo-connect.js';
21
+ import { DatabaseError, EmetError, MONGODB_DB, COLLECTION_PREFIX } from './database.js';
22
+ import { ValidationError } from './validation.js';
23
+ import { digest } from './aleph.js';
24
+ import { setting } from './env.js';
25
+ import { writerStamp } from './persons.js';
26
+ import { isDropDoc } from './conformance.js';
27
+ import { isBotTag } from './session-graph.js';
28
+ import {
29
+ writeDoc, refuseBotMainRecord, sourceRegistry, rightsTags, isRecordDoc, isWorkingDoc
30
+ } from './tools.js';
31
+
32
+ export const STAGED_LIMITS = Object.freeze({
33
+ maxPartChars: 16000,
34
+ maxParts: 128,
35
+ maxTotalChars: 2000000,
36
+ ttlMs: 30 * 60 * 1000,
37
+ maxOpenPerWriter: 4
38
+ });
39
+
40
+ const STAGE_COLLECTION = `${COLLECTION_PREFIX}doc_stages`;
41
+
42
+ function stageFailure(error, tool) {
43
+ if (error instanceof ValidationError || error instanceof EmetError) throw error;
44
+ throw new DatabaseError(`Failed to stage a document write: ${error.message}`, tool, { code: 'EMET-DB-037' });
45
+ }
46
+
47
+ function limitsView() {
48
+ return {
49
+ max_part_chars: STAGED_LIMITS.maxPartChars,
50
+ max_parts: STAGED_LIMITS.maxParts,
51
+ max_total_chars: STAGED_LIMITS.maxTotalChars,
52
+ ttl_minutes: STAGED_LIMITS.ttlMs / 60000,
53
+ max_open_stages: STAGED_LIMITS.maxOpenPerWriter
54
+ };
55
+ }
56
+
57
+ function at(value) {
58
+ if (value instanceof Date) return value.getTime();
59
+ const t = new Date(value).getTime();
60
+ return Number.isFinite(t) ? t : 0;
61
+ }
62
+
63
+ function partIndex(value) {
64
+ if (typeof value === 'number' && Number.isInteger(value) && value >= 1) return value;
65
+ if (typeof value === 'string' && /^\d+$/.test(value.trim())) {
66
+ const n = Number(value.trim());
67
+ if (Number.isSafeInteger(n) && n >= 1) return n;
68
+ }
69
+ return null;
70
+ }
71
+
72
+ function wholeNumber(value) {
73
+ if (typeof value === 'number' && Number.isInteger(value) && value >= 0) return value;
74
+ if (typeof value === 'string' && /^\d+$/.test(value.trim())) {
75
+ const n = Number(value.trim());
76
+ if (Number.isSafeInteger(n) && n >= 0) return n;
77
+ }
78
+ return null;
79
+ }
80
+
81
+ function namedVersion(value) {
82
+ if (value === undefined || value === null || value === '') return null;
83
+ if (typeof value === 'number' && Number.isInteger(value)) return value;
84
+ if (typeof value === 'string' && /^-?\d+$/.test(value.trim())) return Number(value.trim());
85
+ return value;
86
+ }
87
+
88
+ function normalizeSha(value) {
89
+ if (typeof value !== 'string') return null;
90
+ const sha = value.trim().toLowerCase();
91
+ return /^[0-9a-f]{64}$/.test(sha) ? sha : null;
92
+ }
93
+
94
+ function shaMatches(expected, actual) {
95
+ const a = Buffer.from(expected, 'utf8');
96
+ const b = Buffer.from(actual, 'utf8');
97
+ if (a.length !== b.length) return false;
98
+ return timingSafeEqual(a, b);
99
+ }
100
+
101
+ function sameWriter(row, stamp) {
102
+ return row.person_id === stamp.person_id &&
103
+ row.client_id === stamp.client_id &&
104
+ row.grant_id === stamp.grant_id &&
105
+ row.door === stamp.door;
106
+ }
107
+
108
+ async function stageDb() {
109
+ const client = await connectMongo(process.env.MONGODB_URI || 'mongodb://test', { serverSelectionTimeoutMS: 5000, maxPoolSize: 10 });
110
+ const db = client.db(MONGODB_DB);
111
+ return { client, stages: db.collection(STAGE_COLLECTION), docs: db.collection('documents') };
112
+ }
113
+
114
+ function throwExpired(tool) {
115
+ throw new ValidationError(`${tool}: this stage expired. Begin again. Nothing was written.`, { code: 'EMET-DOC-061' });
116
+ }
117
+
118
+ function throwAborted(tool) {
119
+ throw new ValidationError(`${tool}: this stage was aborted. Nothing was written.`, { code: 'EMET-DOC-062' });
120
+ }
121
+
122
+ function throwCommitted(tool) {
123
+ throw new ValidationError(`${tool}: this stage is already committed. Read the document. Nothing was written.`, { code: 'EMET-DOC-063' });
124
+ }
125
+
126
+ function throwCommitting(tool) {
127
+ throw new ValidationError(`${tool}: this stage is already being committed. Nothing was written.`, { code: 'EMET-DOC-076' });
128
+ }
129
+
130
+ /**
131
+ * Load one stage for this writer. An open stage past its TTL is marked expired
132
+ * and refused. A missing id and someone else's id are the same refusal.
133
+ */
134
+ export async function readStage(col, stageId, stamp, tool, now) {
135
+ if (typeof stageId !== 'string' || !stageId.startsWith('stg_')) {
136
+ throw new ValidationError(`${tool}: stage not found for this writer. Nothing was written.`, { code: 'EMET-DOC-060' });
137
+ }
138
+ const row = await col.findOne({ _id: stageId });
139
+ if (!row || !sameWriter(row, stamp)) {
140
+ throw new ValidationError(`${tool}: stage not found for this writer. Nothing was written.`, { code: 'EMET-DOC-060' });
141
+ }
142
+ if (row.status === 'open' && at(row.expires_at) <= at(now)) {
143
+ await col.updateOne(
144
+ { _id: row._id, status: 'open' },
145
+ { $set: { status: 'expired', parts: [], size: 0, updated_at: now } }
146
+ );
147
+ row.status = 'expired';
148
+ row.parts = [];
149
+ row.size = 0;
150
+ }
151
+ if (row.status === 'expired') throwExpired(tool);
152
+ return row;
153
+ }
154
+
155
+ /** Mark this writer's overdue open stages expired and return how many are still open. */
156
+ export async function expireOpenStages(col, stamp, now) {
157
+ const rows = await col.find({
158
+ status: 'open',
159
+ person_id: stamp.person_id,
160
+ client_id: stamp.client_id,
161
+ grant_id: stamp.grant_id,
162
+ door: stamp.door
163
+ }).toArray();
164
+ let live = 0;
165
+ for (const row of rows) {
166
+ if (at(row.expires_at) > at(now)) live += 1;
167
+ else {
168
+ await col.updateOne(
169
+ { _id: row._id, status: 'open' },
170
+ { $set: { status: 'expired', parts: [], size: 0, updated_at: now } }
171
+ );
172
+ }
173
+ }
174
+ return live;
175
+ }
176
+
177
+ function assertCallMatches(tool, row, source, sessionId) {
178
+ if ((source || null) !== (row.source || null)) {
179
+ throw new ValidationError(`${tool}: this call's source does not match the stage. Nothing was written.`, { code: 'EMET-DOC-079' });
180
+ }
181
+ if ((sessionId || null) !== (row.session_id || null)) {
182
+ throw new ValidationError(`${tool}: this call's session does not match the stage. Nothing was written.`, { code: 'EMET-DOC-080' });
183
+ }
184
+ }
185
+
186
+ function assertBeginAllowed(docId, source, prev, supersedes, reason) {
187
+ if (!docId || typeof docId !== 'string') {
188
+ throw new ValidationError('doc_id must be a non-empty string', { code: 'EMET-DOC-001' });
189
+ }
190
+ refuseBotMainRecord(docId, source, 'write_doc');
191
+ if (prev && isRecordDoc(docId)) {
192
+ const named = supersedes;
193
+ if (named === undefined || named === null) {
194
+ throw new ValidationError(
195
+ `write_doc: ${docId} is a record and v${prev.version} is in force. A new revision must name what it ` +
196
+ `supersedes - pass supersedes: ${prev.version}. Nothing was changed.`
197
+ , { code: 'EMET-DOC-017' });
198
+ }
199
+ if (Number(named) !== prev.version) {
200
+ throw new ValidationError(
201
+ `write_doc: ${docId} - supersedes names v${named}, but v${prev.version} is in force. Re-read the record ` +
202
+ `and supersede the current revision. Nothing was changed.`
203
+ , { code: 'EMET-DOC-018' });
204
+ }
205
+ if (typeof reason !== 'string' || reason.trim().length < 10) {
206
+ throw new ValidationError(
207
+ `write_doc: ${docId} is a record. A new revision needs reason (at least 10 characters) as well as supersedes. Nothing was changed.`
208
+ , { code: 'EMET-DOC-019' });
209
+ }
210
+ }
211
+ const registry = sourceRegistry();
212
+ const passes = (t) => registry.length === 0 || registry.includes(t || '') || (isBotTag(t) && docId.startsWith(`bots/${t}/`));
213
+ if (!rightsTags(source).every(passes) && !(isDropDoc(docId) && !prev)) {
214
+ throw new ValidationError(`write_doc: ${source || 'no source'} is not a registered source. This session may read, and may write a new drop only. Nothing was written.`, { code: 'EMET-DOC-020' });
215
+ }
216
+ if (docId === setting('STATE_DOC', 'STATE.md')) {
217
+ if (prev) {
218
+ throw new ValidationError('The board is never written. Edit it with patch_doc, with `reason` (and `origin` for an added row). Nothing was written.', { code: 'EMET-MEM-022' });
219
+ }
220
+ throw new ValidationError('The board is provisioned by the server at setup (emet_setup_complete). Nothing was written.', { code: 'EMET-MEM-023' });
221
+ }
222
+ if (prev && isWorkingDoc(docId)) {
223
+ throw new ValidationError(
224
+ `write_doc: ${docId} exists, so it is edited, not rewritten. Use patch_doc with \`reason\`. Nothing was written.`
225
+ , { code: 'EMET-DOC-022' });
226
+ }
227
+ if (isDropDoc(docId) && prev) {
228
+ throw new ValidationError(
229
+ `write_doc: ${docId} is a drop and already exists, retired drops included. A drop is never patched or restored. Use a new id. Nothing was written.`
230
+ , { code: 'EMET-DOC-023' });
231
+ }
232
+ }
233
+
234
+ function assemble(parts) {
235
+ const ordered = [...(parts || [])].sort((a, b) => a.index - b.index);
236
+ for (let i = 0; i < ordered.length; i++) {
237
+ if (!ordered[i] || ordered[i].index !== i + 1 || typeof ordered[i].text !== 'string') return null;
238
+ }
239
+ return ordered.map((part) => part.text).join('');
240
+ }
241
+
242
+ function receiptOf(row) {
243
+ const receipt = row.receipt || {};
244
+ return {
245
+ doc_id: row.doc_id,
246
+ sha256: receipt.sha256,
247
+ version: receipt.version,
248
+ size: receipt.size,
249
+ updated_at: receipt.updated_at || row.updated_at,
250
+ verified: true,
251
+ stage_id: row._id,
252
+ assembled_sha256: row.assembled_sha256,
253
+ parts: receipt.part_count,
254
+ staged: true,
255
+ already: true
256
+ };
257
+ }
258
+
259
+ export async function beginStagedDoc(input = {}, logger = null, now = new Date()) {
260
+ let client;
261
+ try {
262
+ const opened = await stageDb();
263
+ client = opened.client;
264
+ const docId = input.doc_id;
265
+ const source = input.source || null;
266
+ const sessionId = input.session_id || null;
267
+ const supersedes = namedVersion(input.supersedes);
268
+ const reason = typeof input.reason === 'string' && input.reason.length ? input.reason : null;
269
+ const prev = docId && typeof docId === 'string' ? await opened.docs.findOne({ doc_id: docId }) : null;
270
+ assertBeginAllowed(docId, source, prev, supersedes, reason);
271
+ const stamp = writerStamp();
272
+ const live = await expireOpenStages(opened.stages, stamp, now);
273
+ if (live >= STAGED_LIMITS.maxOpenPerWriter) {
274
+ throw new ValidationError(`write_doc_begin: this writer already has ${STAGED_LIMITS.maxOpenPerWriter} open stages. Commit or abort one, then begin again. Nothing was written.`, { code: 'EMET-DOC-074' });
275
+ }
276
+ const stageId = `stg_${randomBytes(16).toString('hex')}`;
277
+ const expiresAt = new Date(at(now) + STAGED_LIMITS.ttlMs);
278
+ await opened.stages.insertOne({
279
+ _id: stageId,
280
+ doc_id: docId,
281
+ source,
282
+ person_id: stamp.person_id,
283
+ client_id: stamp.client_id,
284
+ grant_id: stamp.grant_id,
285
+ door: stamp.door,
286
+ session_id: sessionId,
287
+ supersedes,
288
+ reason,
289
+ parts: [],
290
+ next_part: 1,
291
+ size: 0,
292
+ status: 'open',
293
+ created_at: now,
294
+ updated_at: now,
295
+ expires_at: expiresAt
296
+ });
297
+ logger?.debug?.('staged write begun', { stage_id: stageId, doc_id: docId });
298
+ return {
299
+ stage_id: stageId,
300
+ doc_id: docId,
301
+ next_part: 1,
302
+ expires_at: expiresAt,
303
+ parts: 0,
304
+ limits: limitsView()
305
+ };
306
+ } catch (error) {
307
+ stageFailure(error, 'write_doc_begin');
308
+ } finally {
309
+ if (client) await client.close().catch(() => {});
310
+ }
311
+ }
312
+
313
+ export async function appendStagedChunk(input = {}, logger = null, now = new Date()) {
314
+ let client;
315
+ try {
316
+ const opened = await stageDb();
317
+ client = opened.client;
318
+ const stamp = writerStamp();
319
+ const row = await readStage(opened.stages, input.stage_id, stamp, 'write_doc_append', now);
320
+ assertCallMatches('write_doc_append', row, input.source, input.session_id);
321
+ if (row.status === 'aborted') throwAborted('write_doc_append');
322
+ if (row.status === 'committed') throwCommitted('write_doc_append');
323
+ if (row.status === 'committing') throwCommitting('write_doc_append');
324
+ if (row.status !== 'open') throwCommitting('write_doc_append');
325
+ const chunk = input.chunk;
326
+ if (typeof chunk !== 'string' || chunk.length === 0) {
327
+ throw new ValidationError('write_doc_append: a staged chunk must be a non-empty string. Nothing was written.', { code: 'EMET-DOC-071' });
328
+ }
329
+ const part = partIndex(input.part);
330
+ if (part === null) {
331
+ throw new ValidationError('write_doc_append: part must be a whole number starting at 1. Nothing was written.', { code: 'EMET-DOC-072' });
332
+ }
333
+ if (chunk.length > STAGED_LIMITS.maxPartChars) {
334
+ throw new ValidationError(`write_doc_append: part ${part} is ${chunk.length} characters and the part limit is ${STAGED_LIMITS.maxPartChars}. Nothing was written.`, { code: 'EMET-DOC-064' });
335
+ }
336
+ const prior = (row.parts || []).find((item) => item.index === part);
337
+ if (prior) {
338
+ if (prior.text !== chunk) {
339
+ throw new ValidationError(`write_doc_append: part ${part} was already stored with different bytes. Nothing was written.`, { code: 'EMET-DOC-066' });
340
+ }
341
+ return {
342
+ stage_id: row._id, part, next_part: row.next_part, parts: row.parts.length,
343
+ size: row.size, expires_at: row.expires_at, duplicate: true
344
+ };
345
+ }
346
+ if (part !== row.next_part) {
347
+ throw new ValidationError(`write_doc_append: part ${part} is out of order. The next part is ${row.next_part}. Nothing was written.`, { code: 'EMET-DOC-065' });
348
+ }
349
+ if (part > STAGED_LIMITS.maxParts) {
350
+ throw new ValidationError(`write_doc_append: a staged write holds at most ${STAGED_LIMITS.maxParts} parts. Nothing was written.`, { code: 'EMET-DOC-068' });
351
+ }
352
+ if (row.size + chunk.length > STAGED_LIMITS.maxTotalChars) {
353
+ throw new ValidationError(`write_doc_append: staged content would exceed the ${STAGED_LIMITS.maxTotalChars} character limit. Nothing was written.`, { code: 'EMET-DOC-067' });
354
+ }
355
+ const claimed = await opened.stages.updateOne(
356
+ {
357
+ _id: row._id, status: 'open', next_part: part,
358
+ person_id: stamp.person_id, client_id: stamp.client_id, grant_id: stamp.grant_id, door: stamp.door
359
+ },
360
+ {
361
+ $inc: { next_part: 1, size: chunk.length },
362
+ $push: { parts: { index: part, text: chunk } },
363
+ $set: { updated_at: now }
364
+ }
365
+ );
366
+ if (claimed.matchedCount !== 1) {
367
+ const again = await readStage(opened.stages, row._id, stamp, 'write_doc_append', now);
368
+ const stored = (again.parts || []).find((item) => item.index === part);
369
+ if (stored && stored.text === chunk) {
370
+ return {
371
+ stage_id: again._id, part, next_part: again.next_part, parts: again.parts.length,
372
+ size: again.size, expires_at: again.expires_at, duplicate: true
373
+ };
374
+ }
375
+ if (stored) {
376
+ throw new ValidationError(`write_doc_append: part ${part} was already stored with different bytes. Nothing was written.`, { code: 'EMET-DOC-066' });
377
+ }
378
+ throw new ValidationError(`write_doc_append: part ${part} is out of order. The next part is ${again.next_part}. Nothing was written.`, { code: 'EMET-DOC-065' });
379
+ }
380
+ logger?.debug?.('staged chunk stored', { stage_id: row._id, part });
381
+ return {
382
+ stage_id: row._id, part, next_part: part + 1, parts: (row.parts || []).length + 1,
383
+ size: row.size + chunk.length, expires_at: row.expires_at, duplicate: false
384
+ };
385
+ } catch (error) {
386
+ stageFailure(error, 'write_doc_append');
387
+ } finally {
388
+ if (client) await client.close().catch(() => {});
389
+ }
390
+ }
391
+
392
+ export async function commitStagedDoc(input = {}, logger = null, now = new Date()) {
393
+ let client;
394
+ try {
395
+ const opened = await stageDb();
396
+ client = opened.client;
397
+ const stamp = writerStamp();
398
+ const row = await readStage(opened.stages, input.stage_id, stamp, 'write_doc_commit', now);
399
+ const sha = normalizeSha(input.sha256);
400
+ if (!sha) {
401
+ throw new ValidationError('write_doc_commit: sha256 must be a 64-character hex digest of the assembled text. Nothing was written.', { code: 'EMET-DOC-073' });
402
+ }
403
+ if (typeof input.doc_id !== 'string' || input.doc_id !== row.doc_id) {
404
+ throw new ValidationError(`write_doc_commit: this commit names a different document than the stage (${row.doc_id}). Nothing was written.`, { code: 'EMET-DOC-075' });
405
+ }
406
+ assertCallMatches('write_doc_commit', row, input.source, input.session_id);
407
+ const named = namedVersion(input.supersedes);
408
+ const supersedesGiven = !(input.supersedes === undefined || input.supersedes === null || input.supersedes === '');
409
+ if (supersedesGiven && named !== row.supersedes) {
410
+ throw new ValidationError('write_doc_commit: supersedes does not match the stage. Nothing was written.', { code: 'EMET-DOC-077' });
411
+ }
412
+ const reasonGiven = typeof input.reason === 'string' && input.reason.length > 0;
413
+ if (reasonGiven && input.reason !== row.reason) {
414
+ throw new ValidationError('write_doc_commit: reason does not match the stage. Nothing was written.', { code: 'EMET-DOC-078' });
415
+ }
416
+ const partCount = wholeNumber(input.part_count);
417
+ if (row.status === 'committed') {
418
+ if (row.receipt && row.assembled_sha256 && shaMatches(sha, row.assembled_sha256) && partCount === row.receipt.part_count) {
419
+ return receiptOf(row);
420
+ }
421
+ throwCommitted('write_doc_commit');
422
+ }
423
+ if (row.status === 'aborted') throwAborted('write_doc_commit');
424
+ if (row.status === 'committing') throwCommitting('write_doc_commit');
425
+ if (row.status !== 'open') throwCommitting('write_doc_commit');
426
+ if (partCount === null || partCount !== (row.parts || []).length) {
427
+ const held = (row.parts || []).length;
428
+ throw new ValidationError(`write_doc_commit: part_count is ${input.part_count} but this stage has ${held} parts. Nothing was written.`, { code: 'EMET-DOC-070' });
429
+ }
430
+ const content = assemble(row.parts);
431
+ if (content === null) {
432
+ throw new ValidationError(`write_doc_commit: part_count is ${partCount} but the stored parts are not contiguous. Nothing was written.`, { code: 'EMET-DOC-070' });
433
+ }
434
+ const assembled = digest(content);
435
+ if (!shaMatches(sha, assembled)) {
436
+ throw new ValidationError('write_doc_commit: sha256 does not match the assembled content. Nothing was written.', { code: 'EMET-DOC-069' });
437
+ }
438
+ const claimed = await opened.stages.updateOne(
439
+ { _id: row._id, status: 'open', person_id: stamp.person_id },
440
+ { $set: { status: 'committing', updated_at: now } }
441
+ );
442
+ if (claimed.matchedCount !== 1) {
443
+ const again = await opened.stages.findOne({ _id: row._id });
444
+ if (again && again.status === 'committed' && again.assembled_sha256 && shaMatches(sha, again.assembled_sha256) && again.receipt && again.receipt.part_count === partCount) {
445
+ return receiptOf(again);
446
+ }
447
+ throwCommitting('write_doc_commit');
448
+ }
449
+ let written;
450
+ try {
451
+ written = await writeDoc(row.doc_id, content, row.source, null, logger, {
452
+ supersedes: row.supersedes,
453
+ reason: row.reason,
454
+ session_id: row.session_id
455
+ });
456
+ } catch (error) {
457
+ await opened.stages.updateOne(
458
+ { _id: row._id, status: 'committing' },
459
+ { $set: { status: 'open', updated_at: new Date() } }
460
+ );
461
+ throw error;
462
+ }
463
+ const receipt = {
464
+ version: written.version,
465
+ sha256: written.sha256,
466
+ size: written.size,
467
+ updated_at: written.updated_at,
468
+ assembled_sha256: assembled,
469
+ part_count: partCount
470
+ };
471
+ await opened.stages.updateOne(
472
+ { _id: row._id, status: 'committing' },
473
+ {
474
+ $set: {
475
+ status: 'committed',
476
+ parts: [],
477
+ size: 0,
478
+ updated_at: now,
479
+ assembled_sha256: assembled,
480
+ part_count: partCount,
481
+ receipt
482
+ }
483
+ }
484
+ );
485
+ logger?.debug?.('staged write committed', { stage_id: row._id, doc_id: row.doc_id, version: written.version });
486
+ return { ...written, stage_id: row._id, assembled_sha256: assembled, parts: partCount, staged: true };
487
+ } catch (error) {
488
+ stageFailure(error, 'write_doc_commit');
489
+ } finally {
490
+ if (client) await client.close().catch(() => {});
491
+ }
492
+ }
493
+
494
+ export async function abortStagedDoc(input = {}, logger = null, now = new Date()) {
495
+ let client;
496
+ try {
497
+ const opened = await stageDb();
498
+ client = opened.client;
499
+ const stamp = writerStamp();
500
+ const row = await readStage(opened.stages, input.stage_id, stamp, 'write_doc_abort', now);
501
+ assertCallMatches('write_doc_abort', row, input.source, input.session_id);
502
+ if (row.status === 'aborted') return { stage_id: row._id, aborted: true, already: true };
503
+ if (row.status === 'committed') throwCommitted('write_doc_abort');
504
+ if (row.status === 'committing') throwCommitting('write_doc_abort');
505
+ if (row.status !== 'open') throwCommitting('write_doc_abort');
506
+ const claimed = await opened.stages.updateOne(
507
+ { _id: row._id, status: 'open', person_id: stamp.person_id },
508
+ { $set: { status: 'aborted', parts: [], size: 0, updated_at: now } }
509
+ );
510
+ if (claimed.matchedCount !== 1) {
511
+ const again = await opened.stages.findOne({ _id: row._id });
512
+ if (again && again.status === 'aborted') return { stage_id: row._id, aborted: true, already: true };
513
+ throwCommitting('write_doc_abort');
514
+ }
515
+ logger?.debug?.('staged write aborted', { stage_id: row._id });
516
+ return { stage_id: row._id, aborted: true, already: false };
517
+ } catch (error) {
518
+ stageFailure(error, 'write_doc_abort');
519
+ } finally {
520
+ if (client) await client.close().catch(() => {});
521
+ }
522
+ }
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Paged startup (ref 358 amendment, paging; Alex approved 2026-10-03, design
2
+ * Paged startup (ref 358 amendment, paging; the owner approved 2026-10-03, design
3
3
  * paper question 1). The connector gateway cuts a tool result at 20,000 UTF-8
4
4
  * bytes, and the full startup is about 64K, so on those hosts the floor,
5
5
  * install notes, source tags, seeds_due, record gaps and lessons never
@@ -42,7 +42,7 @@ export function pageBudget(raw = process.env.EMET_INIT_PAGE_BYTES) {
42
42
 
43
43
  /** Binding first: the order keys are paged in. Keys not listed follow, in payload order. */
44
44
  export const PAGE_ORDER = Object.freeze([
45
- 'state', 'database', 'source_tag', 'source_basis', 'source_login', 'source_remembered', 'approval_state', 'person_id', 'client_approvals', 'unhandled_drops', 'unhandled_drops_more', 'retired_drops', 'emet_line', 'emet_line_if_unanswered',
45
+ 'state', 'database', 'source_tag', 'grant_id', 'door', 'source_basis', 'source_login', 'source_remembered', 'approval_state', 'person_id', 'client_approvals', 'unhandled_drops', 'unhandled_drops_more', 'retired_drops', 'emet_line', 'emet_line_if_unanswered',
46
46
  'tools_in_force', 'instructions_short', 'session_close_protocol', 'operating_discipline', 'charter',
47
47
  'floor', 'floor_precedence', 'floor_reassertion', 'gems_available', 'gems_active',
48
48
  'seeds_due', 'seeds_evaluated_on', 'install_notes_doc_id',
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * The startup payload's size and its abridged form (ref 358 amendment, the
3
3
  * host-aware startup; design: research paper emet-startup-amendment rev 3,
4
- * sections 4a-4c, conservative variant chosen by Alex 2026-10-02, procedural
4
+ * sections 4a-4c, conservative variant chosen by the owner 2026-10-02, procedural
5
5
  * ref 405 item 8 and ref 407).
6
6
  *
7
7
  * WHAT THIS FILE DOES AND DOES NOT DO (2026-10-03):
@@ -21,7 +21,7 @@
21
21
  * - resultSize: the size of a payload as the host receives it, in characters
22
22
  * and UTF-8 bytes (the connector gateway cuts at 20,000 bytes).
23
23
  *
24
- * FIDELITY RULE (Alex, ref 358): the floor, identity, character, user, the close
24
+ * FIDELITY RULE (the owner, ref 358): the floor, identity, character, user, the close
25
25
  * protocol and tools in force are never pointers and never shortened here.
26
26
  * Only install notes, the layer charter and the long instructions become
27
27
  * hash-pinned pointers in the abridged form, and the seed and thread indexes
@@ -59,7 +59,7 @@ export function keySizes(payload) {
59
59
 
60
60
  /** The keys every abridged load embeds exactly as the full load has them (review note 4b; never dropped). */
61
61
  export const ABRIDGED_KEEP = Object.freeze([
62
- 'state', 'database', 'source_tag', 'person_id', 'unhandled_drops', 'unhandled_drops_more', 'retired_drops',
62
+ 'state', 'database', 'source_tag', 'grant_id', 'door', 'person_id', 'unhandled_drops', 'unhandled_drops_more', 'retired_drops',
63
63
  'emet_line', 'emet_line_if_unanswered',
64
64
  'tools_in_force', 'instructions_short', 'session_close_protocol', 'operating_discipline', 'charter',
65
65
  'identity', 'character', 'character_doc_id', 'character_sha256', 'user',
package/src/subkeys.js CHANGED
@@ -19,6 +19,8 @@ import {
19
19
  personIsOwner, actorIsOwner, actorIsCos, cosTag, sessionBaseOf,
20
20
  rememberSubkeySession
21
21
  } from './attribution.js';
22
+ import { isOwlIdentity } from './owl.js';
23
+ import { isMasterBlasterActor } from './writer-approval.js';
22
24
  import { parseReceipts } from './session.js';
23
25
  import { storeFor, sweepFlagOffLiveSessions } from './subkey-store.js';
24
26
 
@@ -428,6 +430,10 @@ export async function decideSubkeyIfPending(deps, actor, ownerId, { tag, decisio
428
430
  const ownerOk = actorIsOwner(actor, ownerId);
429
431
  const cosOk = actorIsCos(actor);
430
432
  if (!(ownerOk || cosOk)) throw refusal(`emet_client_approve: only the owner${cosTag() ? ` or the chief of staff (${cosTag()})` : ''} may decide a sub-key. Nothing was changed.`);
433
+ if (isOwlIdentity(actor)) throw refusal('emet_client_approve: the owl MCP clone account was retired by R6 and cannot approve. the owner decides a new writer on /owner/chooser. Nothing was changed.');
434
+ if (decision === 'approve' && (cosOk || isMasterBlasterActor(actor)) && actor.sourceTag !== 'owner') {
435
+ throw refusal('emet_client_approve: an AI cannot grant a writer. Master Hub prepares a request. the owner decides it on /owner/chooser. Nothing was changed.');
436
+ }
431
437
  const why = typeof reason === 'string' ? reason.trim() : '';
432
438
  const channel = typeof via === 'string' ? via.trim() : '';
433
439
  let result = null;
@@ -598,6 +604,61 @@ export async function revokeSubkey(deps, actor, ownerId, { tag, key_id, reason }
598
604
  return result;
599
605
  }
600
606
 
607
+ const ROTATION_LIVE = new Set(['pending', 'approved', 'active', 'grace']);
608
+
609
+ /**
610
+ * Retire sub-keys for a rotation. tags null is the household. An empty set
611
+ * matches nobody. Rows and session opens stay. Status revoked is not a grace.
612
+ */
613
+ export async function retireSubkeysForRotation(deps, { eventId, tags = null, now = new Date() } = {}) {
614
+ if (!subkeysEnabled()) return { revoked: 0, sessions: 0, skipped: true };
615
+ const store = await storeFor(deps || {});
616
+ if (!store) return { revoked: 0, sessions: 0, unavailable: true };
617
+ if (tags instanceof Set && tags.size === 0) return { revoked: 0, sessions: 0, unavailable: false };
618
+ const at = (now instanceof Date ? now : new Date(now)).toISOString();
619
+ let revoked = 0;
620
+ let sessions = 0;
621
+ await edit(deps, (data) => {
622
+ ensureMaps(data);
623
+ const allow = tags instanceof Set ? tags : null;
624
+ for (const row of Object.values(data.keys)) {
625
+ if (!row || (allow && !allow.has(row.tag)) || !ROTATION_LIVE.has(row.status)) continue;
626
+ row.status = 'revoked';
627
+ row.revoked_at = at;
628
+ row.revoked_by = 'owner';
629
+ row.revoke_reason = 'rotation';
630
+ row.superseded_by = eventId;
631
+ row.retired = true;
632
+ row.deleted = false;
633
+ pushHistory(row, 'revoked', {
634
+ event_id: `h:${row.key_id}:${eventId}`,
635
+ at,
636
+ reason: 'rotation',
637
+ superseded_by: eventId
638
+ });
639
+ row.live_session_id = null;
640
+ row.live_set_at = null;
641
+ revoked += 1;
642
+ }
643
+ for (const s of data.sessions) {
644
+ if (!s || (s.state !== 'live' && s.state !== 'opening')) continue;
645
+ if (allow) {
646
+ const key = Object.values(data.keys).find((item) => item && item.key_id === s.key_id);
647
+ if (!key || !allow.has(key.tag)) continue;
648
+ }
649
+ s.state = 'revoked';
650
+ s.ended_at = at;
651
+ s.end_reason = 'rotation';
652
+ s.superseded_by = eventId;
653
+ s.retained = true;
654
+ s.deleted = false;
655
+ sessions += 1;
656
+ }
657
+ return revoked > 0 || sessions > 0;
658
+ });
659
+ return { revoked, sessions, unavailable: false };
660
+ }
661
+
601
662
  /** End the key's live session without revoking the key. Owner login only. */
602
663
  export async function endSubkeySession(deps, actor, ownerId, { tag, key_id, reason } = {}, now = new Date()) {
603
664
  if (!subkeysEnabled()) throw refusal('sub-keys are off (EMET_SUBKEYS is not 1). Nothing was changed.');