@dreamforgestudiollc/emet 0.2.4 → 0.3.0

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 (116) hide show
  1. package/.env.example +63 -0
  2. package/CHANGELOG.md +84 -3
  3. package/CHARTER.md +19 -7
  4. package/README.md +130 -21
  5. package/areas/emet.md +18 -0
  6. package/areas/garden.md +18 -0
  7. package/areas/health.md +18 -0
  8. package/areas/home.md +18 -0
  9. package/areas/learning.md +18 -0
  10. package/areas/state.md +18 -0
  11. package/docs/AUTHORSHIP.md +3 -3
  12. package/docs/BOTS.md +4 -0
  13. package/docs/COVERAGE.md +2 -2
  14. package/docs/DEPLOY.md +41 -5
  15. package/docs/ERROR-CODES-SPEC.md +43 -0
  16. package/docs/ERROR-CODES.md +332 -0
  17. package/docs/GUARDRAILS-AND-MONORAILS.md +2 -1
  18. package/docs/GUIDED-SETUP.md +24 -3
  19. package/docs/PERMISSIONS.md +13 -7
  20. package/docs/ROADMAP.md +18 -15
  21. package/docs/SETUP.md +123 -14
  22. package/docs/SUBKEYS.md +59 -0
  23. package/gems/artifact-index.json +12 -0
  24. package/gems/bot-team-backup/floor.json +15 -0
  25. package/gems/bot-team-backup/gem.json +43 -0
  26. package/gems/bot-team-backup/guides/BOT_TEAM_BACKUP.md +27 -0
  27. package/gems/bot-team-backup/guides/BOT_TEAM_RECOVERY.md +23 -0
  28. package/gems/fieldnote/floor.json +14 -0
  29. package/gems/fieldnote/gem.json +70 -0
  30. package/gems/fieldnote/runes/fieldnote.js +4 -0
  31. package/gems/lean-six-sigma/CHANGELOG.md +10 -0
  32. package/gems/lean-six-sigma/README.md +92 -0
  33. package/gems/lean-six-sigma/floor.json +31 -0
  34. package/gems/lean-six-sigma/gem.json +1296 -0
  35. package/gems/lean-six-sigma/guides/ASSUMPTIONS.md +45 -0
  36. package/gems/lean-six-sigma/guides/BELTS.md +52 -0
  37. package/gems/lean-six-sigma/guides/DMADV.md +56 -0
  38. package/gems/lean-six-sigma/guides/DMAIC.md +127 -0
  39. package/gems/lean-six-sigma/guides/FORMULAS.md +330 -0
  40. package/gems/lean-six-sigma/guides/LEAN.md +97 -0
  41. package/gems/lean-six-sigma/guides/TEMPLATES.md +279 -0
  42. package/gems/lean-six-sigma/runes/lss_capability.js +132 -0
  43. package/gems/lean-six-sigma/runes/lss_control_limits.js +240 -0
  44. package/gems/lean-six-sigma/runes/lss_dpmo_sigma.js +81 -0
  45. package/gems/lean-six-sigma/runes/lss_hypothesis.js +298 -0
  46. package/gems/lean-six-sigma/runes/lss_sample_size.js +81 -0
  47. package/gems/neurendipity/floor.json +65 -0
  48. package/gems/neurendipity/gem.json +42 -0
  49. package/gems/neurendipity/guides/AUTISTIC_BURNOUT.md +81 -0
  50. package/{guides → gems/neurendipity/guides}/NEURODIVERGENT_SUPPORT.md +17 -8
  51. package/guides/README.md +3 -0
  52. package/package.json +12 -5
  53. package/server.json +48 -4
  54. package/src/aleph.js +18 -12
  55. package/src/annotations.js +45 -5
  56. package/src/atlas-role.js +9 -4
  57. package/src/attribution.js +555 -0
  58. package/src/conformance.js +7 -5
  59. package/src/database.js +34 -17
  60. package/src/dispatch.js +136 -16
  61. package/src/env.js +54 -9
  62. package/src/error-codes.js +394 -0
  63. package/src/error-log.js +273 -0
  64. package/src/error-report.js +245 -0
  65. package/src/floor.js +84 -41
  66. package/src/gaps.js +41 -8
  67. package/src/gem-check.js +1360 -0
  68. package/src/guides.js +31 -4
  69. package/src/host-reach.js +23 -0
  70. package/src/http-remote.js +47 -2
  71. package/src/index.js +10 -2
  72. package/src/invites.js +6 -5
  73. package/src/layers.js +9 -8
  74. package/src/lessons-to-checks.js +3 -3
  75. package/src/logger.js +2 -1
  76. package/src/mongo-connect.js +50 -2
  77. package/src/oauth-provider.js +30 -29
  78. package/src/owner-approvals.js +281 -0
  79. package/src/pages.js +806 -0
  80. package/src/persons.js +22 -1
  81. package/src/provenance.js +10 -10
  82. package/src/redact.js +10 -4
  83. package/src/request-log.js +1 -1
  84. package/src/rune-dispatch.js +360 -0
  85. package/src/rune-registry.js +71 -0
  86. package/src/rune-scope.js +42 -0
  87. package/src/scopes.js +3 -0
  88. package/src/session-graph.js +15 -12
  89. package/src/session.js +10 -10
  90. package/src/setup.js +307 -36
  91. package/src/socket.js +545 -0
  92. package/src/startup-pages.js +26 -8
  93. package/src/startup-payload.js +12 -8
  94. package/src/subkey-store.js +358 -0
  95. package/src/subkeys.js +947 -0
  96. package/src/tools.js +518 -204
  97. package/src/transcript-session.js +1 -1
  98. package/src/validation.js +85 -52
  99. package/src/version.js +1 -1
  100. package/templates/AREA.md +35 -0
  101. package/templates/BOARD.md +2 -2
  102. package/templates/BOTHANDOFF.md +2 -2
  103. package/templates/CHARACTER.md +1 -1
  104. package/templates/HANDOFF.md +1 -1
  105. package/templates/IDENTITY.md +1 -1
  106. package/templates/INDEX.md +21 -20
  107. package/templates/INSTALL.md +1 -1
  108. package/templates/PROCEDURE.md +1 -1
  109. package/templates/ROSTER.md +2 -2
  110. package/templates/SEED.md +2 -2
  111. package/templates/STAGING.md +2 -2
  112. package/templates/STANDARD.md +5 -5
  113. package/templates/THREAD.md +1 -1
  114. package/templates/USER.md +4 -1
  115. package/verification/load-gate/corpus.json +1765 -0
  116. package/verification/load-gate/load-gate.mjs +1246 -0
package/src/setup.js CHANGED
@@ -21,11 +21,14 @@ import fs from 'fs';
21
21
  import path from 'path';
22
22
  import crypto from 'crypto';
23
23
  import { resolveModulePath } from './module-path.js';
24
- import { setting } from './env.js';
24
+ import { setting, parseEnvAssignments, platformEnv, realEnvIsConfigSource } from './env.js';
25
+ import { approvedTags, cachedApprovals, approvalsView, rememberedView } from './attribution.js';
26
+ import { declaredAttribution, rawActor } from './persons.js';
25
27
  import { MONGODB_URI, MONGODB_DB, COLLECTION_PREFIX, DatabaseError, EmetDatabase } from './database.js';
26
28
  import { VALID_LAYERS, ValidationError } from './validation.js';
27
29
  import { DISCIPLINE_SUMMARY } from './disciplines.js';
28
30
  import { FLOOR, FLOOR_REASSERTION, PRECEDENCE as FLOOR_PRECEDENCE } from './floor.js';
31
+ import { seatGems } from './socket.js';
29
32
  import { LAYER_SUMMARY, assessLayerHealth } from './layers.js';
30
33
  import { CLOSE_PROTOCOL, handoffDoc, stateDoc } from './session.js';
31
34
  import { currentActor } from './persons.js';
@@ -39,6 +42,8 @@ function callerHoldsWriteScope() {
39
42
  return scopes.includes('emet.write') || scopes.includes('emet') || scopes.includes('*');
40
43
  }
41
44
  import { gapCounts } from './gaps.js';
45
+ import { pageLintDigest } from './pages.js';
46
+ import { registerSecretsFromEnv } from './redact.js';
42
47
  import { payloadForLayerCharter } from './startup-payload.js';
43
48
  import { namedItemsFrom } from './named-items.js';
44
49
  import { paginate, cacheLoad, cachedLoad, loadIdOf, restartPage, notePageServed, wholeStartup } from './startup-pages.js';
@@ -46,6 +51,7 @@ import { paginate, cacheLoad, cachedLoad, loadIdOf, restartPage, notePageServed,
46
51
  const DOCS_COLLECTION = 'documents';
47
52
  const CHARTER_DOC = 'CHARTER.md';
48
53
  const CHARTER_FILE = resolveModulePath(import.meta.url, ['..', 'CHARTER.md']);
54
+ export const ENV_FILE = resolveModulePath(import.meta.url, ['..', '.env']);
49
55
  const IDENTITY_DOC = 'bootstrap/IDENTITY.md';
50
56
  const USER_DOC = 'bootstrap/USER.md';
51
57
 
@@ -166,7 +172,7 @@ async function resolveCharacterDoc(docs, override) {
166
172
  * names in both places. Rule stated once, in the architecture charter; this is
167
173
  * the code half of it.
168
174
  *
169
- * PARKED ITEMS ARE NAMED TOO (2026-09-23, a decision record). This list used to
175
+ * PARKED ITEMS ARE NAMED TOO (2026-09-23, procedural ref 355). This list used to
170
176
  * end with "leave out items the user has parked" - which is the same failure
171
177
  * one step removed: for a neurodivergent user, what they deliberately set aside
172
178
  * drops out of mind exactly as fast as what they forgot. The user, verbatim:
@@ -176,7 +182,7 @@ async function resolveCharacterDoc(docs, override) {
176
182
  * items are named in a section of their own, with what brings each one back, and
177
183
  * nothing is asked of them. Visible is not owed.
178
184
  */
179
- export function startupListInstructions() {
185
+ export function startupListInstructions(available) {
180
186
  return (
181
187
  'Then, before any question, read `' + handoffDoc() + '` and `' + stateDoc() + '` ' +
182
188
  '(read_doc) if this store has them, and name the user\'s items for them: ' +
@@ -194,6 +200,7 @@ export function startupListInstructions() {
194
200
  'times it has landed; ask nothing of them. Each is settled by a new meta entry carrying the ' +
195
201
  'family tags and metadata.lesson_disposition {kind: check|document|uncheckable, ref}. ' +
196
202
  seedsAndThreadsInstructions() + ' ' +
203
+ gemStartupLine(available) + ' ' +
197
204
  'Never open with a question alone. If this store has neither document, say so once ' +
198
205
  'rather than inventing a list.'
199
206
  );
@@ -239,7 +246,16 @@ function retirementFields(row) {
239
246
 
240
247
  /** The registered source tags (EMET_SOURCE_TAGS), as a list. */
241
248
  export function registeredSourceTags() {
242
- return String(setting('SOURCE_TAGS') ?? '').split(',').map((s) => s.trim()).filter(Boolean);
249
+ const env = String(setting('SOURCE_TAGS') ?? '').split(',').map((s) => s.trim()).filter(Boolean);
250
+ return env.length ? [...new Set([...env, ...approvedTags()])] : env;
251
+ }
252
+
253
+ /** Attribution v2: the caller's real tag, not the server-wide default (Alex 2026-10-12 (c)). */
254
+ export function callerAttribution() {
255
+ const d = declaredAttribution();
256
+ if (!d) return { source_tag: setting('SOURCE_TAG') || null };
257
+ const tag = d.effective || d.login || null;
258
+ return { source_tag: tag, source_basis: d.basis || (tag ? 'login' : 'none'), ...(d.login && d.login !== tag ? { source_login: d.login } : {}), approval_state: d.approval || (d.basis === 'login' ? 'login' : 'unknown'), ...((() => { const v = rememberedView({ rememberedTags: d.rememberedTags, declaredTag: d.declared || d.effective }); return v ? { source_remembered: v } : {}; })()) };
243
259
  }
244
260
 
245
261
  export function hostSetupInstructions() {
@@ -310,7 +326,7 @@ export function summarizeSeed(doc_id, text, today = new Date().toISOString().sli
310
326
  }
311
327
 
312
328
  /**
313
- * One line per seed for the initialize payload (the owner, 2026-09-27, code audit
329
+ * One line per seed for the initialize payload (Alex, 2026-09-27, code audit
314
330
  * 2.3: "seeds can be one line since follow-up inquiry by the user will expand
315
331
  * it"). Before this every trigger's full test text was served - 13K characters
316
332
  * for 21 seeds with none due. The line keeps what a startup scan needs: the
@@ -363,7 +379,28 @@ export const EMET_LINE_UNANSWERED = 'MET — the aleph is missing. Memory not co
363
379
  * the rest. This is the subset that must survive a cut; the long form still
364
380
  * follows at the end and governs wording where the two differ.
365
381
  */
366
- export function shortInstructions() {
382
+ /** The sentence an empty GEM list prints. Tests strip this exact text, trailing space included. */
383
+ export const GEMS_NONE_LINE = 'GEMs installed: none.';
384
+
385
+ /**
386
+ * One line per installed GEM: id, name, and on or off. A refused GEM adds the
387
+ * reason code and nothing else. An empty list still names itself.
388
+ */
389
+ export function gemStartupLine(available) {
390
+ const list = Array.isArray(available) ? available : [];
391
+ if (list.length === 0) return GEMS_NONE_LINE;
392
+ return list.map((gem) => {
393
+ const id = gem && typeof gem.id === 'string' ? gem.id : 'unknown';
394
+ const name = gem && typeof gem.name === 'string' && gem.name ? gem.name : id;
395
+ const flag = gem && gem.active === true ? 'on' : 'off';
396
+ const why = gem && gem.loadable === false && typeof gem.reason === 'string' ? ` ${gem.reason}` : '';
397
+ const runes = gem && gem.active === true && Array.isArray(gem.runes) ? gem.runes : [];
398
+ const served = runes.map((rune) => ` ${rune.name} runtime ${rune.runtime} inputs ${rune.inputs} outputs ${rune.outputs} sha256 ${rune.sha256}`).join('');
399
+ return `${id}, ${name}, ${flag}${why}${served}`;
400
+ }).join('\n');
401
+ }
402
+
403
+ export function shortInstructions(available) {
367
404
  return (
368
405
  'Read in this order if the payload is cut short. (1) Say `emet_line` exactly, alone; then ' +
369
406
  'the identity phrase from `identity` exactly, if one is set. (2) `identity`, `character`, ' +
@@ -372,7 +409,7 @@ export function shortInstructions() {
372
409
  'host\'s source tag. (4) After every startup page, call emet_session_open with its load_id, then say every name in ' +
373
410
  '`named_items` (half-state, dated within seven days, open, undecided, then parked under its own heading, never pressed). ' +
374
411
  'Read HANDOFF.md and STATE.md when a section is marked unread. Then `lessons_pending`. A count is the check, never the list. ' +
375
- 'Never open with a question alone. (5) Append every exchange with ' +
412
+ gemStartupLine(available) + ' Never open with a question alone. (5) Append every exchange with ' +
376
413
  'emet_transcript_append; pass session_id and exchange on every write; follow ' +
377
414
  '`session_graph.next`. (6) Close per ' +
378
415
  '`session_close_protocol`; handoff last; saved only ' +
@@ -407,7 +444,7 @@ export function startupIndicatorInstructions() {
407
444
  * stand alone, because on its own it reads as "say nothing" and the user's
408
445
  * items drop out of sight with it.
409
446
  */
410
- export function readyInstructions(hasCharacter) {
447
+ export function readyInstructions(hasCharacter, available) {
411
448
  const core =
412
449
  'Before answering anything that may have prior context, search memory first ' +
413
450
  'rather than assuming. `layer_charter` says what belongs in each of the six layers - use ' +
@@ -439,7 +476,7 @@ export function readyInstructions(hasCharacter) {
439
476
  'where things stood; do not recite this payload back, list the layer counts, or announce ' +
440
477
  'that you loaded memory; if nothing in recent_context bears on what they ask first, leave ' +
441
478
  'recent_context out of the greeting. ' + hostSetupInstructions() + ' ' +
442
- startupListInstructions() + ' ' + core
479
+ startupListInstructions(available) + ' ' + core
443
480
  );
444
481
  }
445
482
 
@@ -454,13 +491,13 @@ export function readyInstructions(hasCharacter) {
454
491
  'Open with a short greeting that shows you know where things stood - do not recite ' +
455
492
  'this payload back, do not list the layer counts, and do not announce that you loaded ' +
456
493
  'memory. If nothing in recent_context is relevant to what they ask next, say nothing ' +
457
- 'about it. ' + hostSetupInstructions() + ' ' + startupListInstructions() + ' ' + core
494
+ 'about it. ' + hostSetupInstructions() + ' ' + startupListInstructions(available) + ' ' + core
458
495
  );
459
496
  }
460
497
 
461
498
  async function connect() {
462
499
  if (!MONGODB_URI) {
463
- throw new ValidationError('MONGODB_URI is not set. Copy .env.example to .env and fill it in.');
500
+ throw new ValidationError('MONGODB_URI is not set. Copy .env.example to .env and fill it in.', { code: 'EMET-DB-001' });
464
501
  }
465
502
  const client = await connectMongo(MONGODB_URI, { serverSelectionTimeoutMS: 8000, maxPoolSize: 5 });
466
503
  return { client, db: client.db(MONGODB_DB) };
@@ -492,9 +529,155 @@ export const SETUP_INTERVIEW = Object.freeze([
492
529
  why: 'Recorded as standing preferences rather than relearned each session.' },
493
530
  { key: 'source_tag', required: false,
494
531
  ask: 'What should writes from THIS host be tagged as? (e.g. laptop, phone, cli)',
495
- why: 'Every write records its origin. A shared default tag makes provenance meaningless once a second host connects.' }
532
+ why: 'Every write records its origin. A shared default tag makes provenance meaningless once a second host connects.' },
533
+ { key: 'more_than_one_bot', required: false,
534
+ ask: 'Will more than one bot or AI use this memory? Answer yes or no.',
535
+ why: 'Yes turns on delegated client sub-keys when this server reads .env. No, or leaving it out, leaves them off. A hosted server does not write a pepper; it tells you the three settings to put in the platform\'s variables. Each bot\'s tag must be listed in EMET_SOURCE_TAGS. See docs/SUBKEYS.md.' },
536
+ { key: 'bot_team_backup', required: false,
537
+ ask: 'Turn on bot-team backup? It is off unless you say yes. Yes is the recommended choice. Answer yes or no.',
538
+ why: 'Yes records that choice and means the assistant follows the bot-team backup recipe: each bot\'s name, prompt, settings, routines and skills are written as controlled documents, revised only when they change. No, or leaving it out, leaves the practice off. EMET does not copy those documents itself, and secret values are never stored. See gems/bot-team-backup/guides/BOT_TEAM_BACKUP.md.' }
496
539
  ]);
497
540
 
541
+ /**
542
+ * yes or no from the interview. Absent means no. Anything else is not an
543
+ * answer, and setup does not invent one.
544
+ */
545
+ export function parseMoreThanOneBot(value) {
546
+ if (value == null || String(value).trim() === '') return false;
547
+ const s = String(value).trim().toLowerCase().replace(/[.!]+$/, '');
548
+ if (s === 'yes' || s === 'y' || s === 'true') return true;
549
+ if (s === 'no' || s === 'n' || s === 'false') return false;
550
+ return null;
551
+ }
552
+
553
+ /**
554
+ * yes or no from the interview, in the user's words, the same way as
555
+ * more_than_one_bot. Absent means no. A non-string is not an answer.
556
+ * "Yes" and "Yes." are yes. Anything else is refused before a write.
557
+ */
558
+ export function parseBotTeamBackup(value) {
559
+ if (value == null) return false;
560
+ if (typeof value !== 'string') return null;
561
+ const s = value.trim().toLowerCase().replace(/[.!]+$/, '');
562
+ if (s === '') return false;
563
+ if (s === 'yes' || s === 'y' || s === 'true') return true;
564
+ if (s === 'no' || s === 'n' || s === 'false') return false;
565
+ return null;
566
+ }
567
+
568
+ /** Steps returned when yes is refused because real env vars are the config source. Thrown before any store write. */
569
+ export const HOSTED_SUBKEY_STEPS =
570
+ 'This server takes its settings from the platform, not from a .env file, so setup will not write a pepper here. No pepper or .env was written. ' +
571
+ 'Run setup again without yes to finish the rest. ' +
572
+ 'The platform-variable steps are in docs/SUBKEYS.md: set EMET_SUBKEYS=1, EMET_SUBKEY_PEPPER (generate it yourself, at least 32 bytes, for example with openssl rand -hex 32), and EMET_SUBKEY_PEPPER_VERSION=1, then redeploy. ' +
573
+ 'Do not paste the pepper into the chat or into any EMET document.';
574
+
575
+ /** .env is writable only when this process actually loaded that file, and no platform is injecting the environment. */
576
+ export function dotenvWritable(envFile = ENV_FILE, env = process.env, startup) {
577
+ if (platformEnv(env)) return false;
578
+ if (path.resolve(envFile) !== path.resolve(ENV_FILE)) return true;
579
+ return !realEnvIsConfigSource(env, startup);
580
+ }
581
+
582
+ function pepperStrong(value) {
583
+ return typeof value === 'string' && Buffer.byteLength(value) >= 32;
584
+ }
585
+
586
+ /** Replace active KEY= lines. Commented lines stay. Missing keys are appended. */
587
+ export function upsertEnvAssignments(text, assignments) {
588
+ const lines = String(text ?? '').replace(/\r\n/g, '\n').split('\n');
589
+ if (lines.length && lines[lines.length - 1] === '') lines.pop();
590
+ const seen = new Set();
591
+ const out = lines.map((line) => {
592
+ const trimmed = line.trim();
593
+ if (!trimmed || trimmed.startsWith('#')) return line;
594
+ const eq = trimmed.indexOf('=');
595
+ if (eq < 1) return line;
596
+ const key = trimmed.slice(0, eq).trim();
597
+ if (!Object.prototype.hasOwnProperty.call(assignments, key)) return line;
598
+ seen.add(key);
599
+ const lead = (line.match(/^\s*/) || [''])[0];
600
+ return `${lead}${key}=${assignments[key]}`;
601
+ });
602
+ const missing = Object.keys(assignments).filter((key) => !seen.has(key));
603
+ if (missing.length) {
604
+ if (out.length && out[out.length - 1] !== '') out.push('');
605
+ out.push('# Written by first-use setup. The pepper is a server secret. Do not commit this file.');
606
+ for (const key of missing) out.push(`${key}=${assignments[key]}`);
607
+ }
608
+ return `${out.join('\n')}\n`;
609
+ }
610
+
611
+ /**
612
+ * Turn the existing sub-key flag on. A single client does not call this.
613
+ *
614
+ * Default-on was rejected. A single client has one login and one tag, so the
615
+ * flag does not change what it can write. The sub-key tools fail closed
616
+ * without a pepper of at least 32 bytes. A phone or a web project cannot
617
+ * store a key file and keeps the tag on its own connection. The tools, the
618
+ * owner page and the store already ship. This only writes EMET_SUBKEYS=1, a
619
+ * pepper, and EMET_SUBKEY_PEPPER_VERSION=1. The pepper is not returned. An
620
+ * existing strong pepper is kept, not rotated. This does not set process.env:
621
+ * the flag takes effect on restart, with the tools and /owner/approvals together.
622
+ * A hosted process, where real env vars are the config source, is refused
623
+ * instead of writing a pepper into the container.
624
+ */
625
+ export function enableSubkeysAtFirstUse({ envFile = ENV_FILE, env = process.env, startup } = {}) {
626
+ if (!dotenvWritable(envFile, env, startup)) {
627
+ throw new ValidationError('more_than_one_bot', HOSTED_SUBKEY_STEPS, { code: 'EMET-CFG-004' });
628
+ }
629
+ let raw = '';
630
+ try {
631
+ raw = fs.readFileSync(envFile, 'utf8');
632
+ } catch (e) {
633
+ if (!e || e.code !== 'ENOENT') {
634
+ throw new ValidationError('more_than_one_bot', 'Could not read .env. Sub-keys were not turned on.', { code: 'EMET-CFG-005' });
635
+ }
636
+ }
637
+ const fromFile = parseEnvAssignments(raw);
638
+ const current = pepperStrong(env.EMET_SUBKEY_PEPPER) ? env.EMET_SUBKEY_PEPPER
639
+ : (pepperStrong(fromFile.EMET_SUBKEY_PEPPER) ? fromFile.EMET_SUBKEY_PEPPER : null);
640
+ const pepper = current || crypto.randomBytes(32).toString('hex');
641
+ const versionNum = Number(env.EMET_SUBKEY_PEPPER_VERSION || fromFile.EMET_SUBKEY_PEPPER_VERSION);
642
+ const version = Number.isInteger(versionNum) && versionNum > 0 ? String(versionNum) : '1';
643
+ const next = upsertEnvAssignments(raw, {
644
+ EMET_SUBKEYS: '1',
645
+ EMET_SUBKEY_PEPPER: pepper,
646
+ EMET_SUBKEY_PEPPER_VERSION: version
647
+ });
648
+ const tmp = path.join(path.dirname(envFile), `.env.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`);
649
+ try {
650
+ fs.writeFileSync(tmp, next, { mode: 0o600 });
651
+ fs.renameSync(tmp, envFile);
652
+ } catch (e) {
653
+ try { fs.unlinkSync(tmp); } catch { /* the temp file may not exist */ }
654
+ throw new ValidationError('more_than_one_bot', 'Could not write .env. Sub-keys were not turned on.', { code: 'EMET-CFG-006' });
655
+ }
656
+ // The flag stays off in this process. Tools and /owner/approvals appear together on restart.
657
+ // Register the pepper so a later write that contains it is masked.
658
+ registerSecretsFromEnv({ EMET_SUBKEY_PEPPER: pepper });
659
+ return {
660
+ enabled: true,
661
+ turned_on: true,
662
+ pepper_generated: current === null,
663
+ pepper_version: Number(version),
664
+ restart_for_owner_page: true
665
+ };
666
+ }
667
+
668
+ /** Two sentences and a pointer. The steps live in docs/SUBKEYS.md. The pepper is never in this note. */
669
+ export function subkeySetupNote(multi, subkeys) {
670
+ if (multi && subkeys && subkeys.env_error) {
671
+ if (subkeys.env_error === HOSTED_SUBKEY_STEPS) return HOSTED_SUBKEY_STEPS;
672
+ return 'The store is set up. Sub-keys were not turned on because .env could not be written. See docs/SUBKEYS.md.';
673
+ }
674
+ if (multi && subkeys && subkeys.enabled) {
675
+ return 'Sub-keys were written to .env. The pepper is not in this result. Restart (or redeploy) the server once so the tools and /owner/approvals appear together. Each bot\'s tag must be listed in EMET_SOURCE_TAGS. See docs/SUBKEYS.md.';
676
+ }
677
+ if (setting('SUBKEYS') === '1') return 'Sub-keys were already on. This answer does not turn them off.';
678
+ return 'Sub-keys stay off. See docs/SUBKEYS.md.';
679
+ }
680
+
498
681
  export async function setupBegin() {
499
682
  const state = await setupStatus();
500
683
  return {
@@ -505,6 +688,8 @@ export async function setupBegin() {
505
688
  instructions:
506
689
  'Ask the user these questions conversationally - one at a time, in their own words, not as a form. ' +
507
690
  'Do not invent answers, and do not fill in an answer the user did not give. ' +
691
+ 'more_than_one_bot is optional. Yes or no, in the user\'s words. Leaving it out leaves sub-keys off. ' +
692
+ 'bot_team_backup is optional. Yes is the recommended choice. No, or leaving it out, leaves bot-team backup off. ' +
508
693
  'When you have them, call emet_setup_complete with an `answers` object keyed exactly as below.',
509
694
  questions: SETUP_INTERVIEW.map(q => ({ key: q.key, ask: q.ask, why: q.why, required: q.required }))
510
695
  };
@@ -682,7 +867,7 @@ export async function initialize(options = {}, hooks = {}) {
682
867
  if (late && late.length && typeof hooks.onLate === 'function') { try { hooks.onLate(late); } catch { /* recording never fails a page */ } }
683
868
  return late;
684
869
  };
685
- // Paged startup (2026-10-03, the owner approved paging; src/startup-pages.js).
870
+ // Paged startup (2026-10-03, Alex approved paging; src/startup-pages.js).
686
871
  // The full payload is built exactly as before; only its delivery changes.
687
872
  const raw = options.page;
688
873
  const wantAll = typeof raw === 'string' && raw.trim().toLowerCase() === 'all';
@@ -691,7 +876,7 @@ export async function initialize(options = {}, hooks = {}) {
691
876
  // A number, or the text of one; anything else (true, "two", 2.5) is refused, never read as page 1.
692
877
  k = typeof raw === 'number' ? raw : (typeof raw === 'string' && /^\s*\d+\s*$/.test(raw) ? Number(raw) : NaN);
693
878
  if (!Number.isInteger(k) || k < 1) {
694
- throw new ValidationError('page', 'page is a whole number from 1 (the startup is served in pages; start with no page, or page 1), or "all" for the whole startup in one result on a host with no size limit.');
879
+ throw new ValidationError('page', 'page is a whole number from 1 (the startup is served in pages; start with no page, or page 1), or "all" for the whole startup in one result on a host with no size limit.', { code: 'EMET-CFG-007' });
695
880
  }
696
881
  }
697
882
  // Every startup carries a load_id (2026-10-03), so every host can open a
@@ -708,7 +893,7 @@ export async function initialize(options = {}, hooks = {}) {
708
893
  // its load_id. A ready startup today never does (~27K minimum).
709
894
  if (pages.length === 1) return whole(full, 1);
710
895
  if (k > pages.length) {
711
- throw new ValidationError('page', `this startup has ${pages.length} pages; page ${k} does not exist.`);
896
+ throw new ValidationError('page', `this startup has ${pages.length} pages; page ${k} does not exist.`, { code: 'EMET-CFG-008' });
712
897
  }
713
898
  notePage(pages[k - 1].startup_page.load_id, k, pages.length);
714
899
  return pages[k - 1];
@@ -749,8 +934,23 @@ export async function initialize(options = {}, hooks = {}) {
749
934
  let startupBuildForTests = null;
750
935
  export function setStartupBuildForTests(fn) { startupBuildForTests = typeof fn === 'function' ? fn : null; }
751
936
 
937
+ /** Seat GEMs for this startup. A throw here still returns empty lists. */
938
+ async function loadSeatedGems() {
939
+ try {
940
+ return await seatGems();
941
+ } catch {
942
+ // SR-07: the session is never what fails. One line, no stack in the payload.
943
+ console.error('emet: GEM socket failed closed');
944
+ return { gems_available: [], gems_active: [] };
945
+ }
946
+ }
947
+
752
948
  /** The full startup payload, in one object: what initialize returned before paging. */
753
949
  async function buildStartup(options = {}) {
950
+ const seated = await loadSeatedGems();
951
+ const gems_available = seated.gems_available;
952
+ const gems_active = seated.gems_active;
953
+ const gemLine = gemStartupLine(gems_available);
754
954
  const status = await setupStatus();
755
955
 
756
956
  if (!status.reachable) {
@@ -769,7 +969,9 @@ async function buildStartup(options = {}) {
769
969
  'the user plainly that the memory store cannot be reached, and what the ' +
770
970
  'problem is. Do not proceed as though memory is available, and do not invent ' +
771
971
  'continuity you do not have. `charter` is still present: it ships with the release, not ' +
772
- 'the store, so it is readable even now. docs/SETUP.md has a failure table.'
972
+ 'the store, so it is readable even now. docs/SETUP.md has a failure table. ' + gemLine,
973
+ gems_available,
974
+ gems_active
773
975
  };
774
976
  }
775
977
 
@@ -793,7 +995,9 @@ async function buildStartup(options = {}) {
793
995
  'Do NOT run the setup interview and do NOT offer to create an identity. This store already ' +
794
996
  'holds memory that this server is not configured to see. Tell the user plainly what was ' +
795
997
  'found and what to change, and stop. Creating a second identity here would leave two ' +
796
- 'disconnected memories in one database.'
998
+ 'disconnected memories in one database. ' + gemLine,
999
+ gems_available,
1000
+ gems_active
797
1001
  };
798
1002
  }
799
1003
 
@@ -824,8 +1028,11 @@ async function buildStartup(options = {}) {
824
1028
  'This memory store is new. Do not report a list of questions back to the user. ' +
825
1029
  'Explain in a sentence that you have no memory of them yet and would like to set that ' +
826
1030
  'up, then ask these questions conversationally, one at a time, in your own words. ' +
827
- 'Never invent or assume an answer. When you have them, call emet_setup_complete.',
828
- questions: begin.questions
1031
+ 'Never invent or assume an answer. One question is optional, yes or no: whether more than one bot or AI will use this memory. Leaving it out leaves sub-keys off. ' +
1032
+ 'When you have them, call emet_setup_complete. ' + gemLine,
1033
+ questions: begin.questions,
1034
+ gems_available,
1035
+ gems_active
829
1036
  };
830
1037
  }
831
1038
 
@@ -914,8 +1121,8 @@ async function buildStartup(options = {}) {
914
1121
  lessonsPending = { assessed: false, error: e && e.message ? e.message : String(e), pending: [] };
915
1122
  }
916
1123
 
917
- // Stage 1 of the host-aware startup amendment (2026-10-02; the owner's decision 2,
918
- // the owner's decision record: "emet_initialize is the startup doorway every bot
1124
+ // Stage 1 of the ref 358 startup amendment (2026-10-02; the owner's decision 2,
1125
+ // procedural ref 407: "emet_initialize is the startup doorway every bot
919
1126
  // calls; only first-time setup stays the owner's"). Initialize no longer creates
920
1127
  // the owner person: that write moved to setupComplete, the owner's
921
1128
  // first-time setup, so initialize is read-only in every branch and matches
@@ -930,12 +1137,20 @@ async function buildStartup(options = {}) {
930
1137
  const openDrops = dropRows.filter((d) => d.retired !== true);
931
1138
  const retiredDrops = dropRows.filter((d) => d.retired === true);
932
1139
  const shown = openDrops.slice(0, 20);
1140
+ let subkeys = null;
1141
+ if (setting('SUBKEYS') === '1') {
1142
+ const { subkeysView, loadSubkeyRecords } = await import('./subkeys.js');
1143
+ const { approvalsDeps } = await import('./tools.js');
1144
+ subkeys = subkeysView(await loadSubkeyRecords(approvalsDeps), rawActor() || { transport: 'stdio' }, personId, new Date());
1145
+ }
933
1146
 
934
1147
  return {
935
1148
  state: 'ready',
936
1149
  database: status.database,
937
- source_tag: setting('SOURCE_TAG') || null,
1150
+ ...callerAttribution(),
938
1151
  person_id: personId,
1152
+ ...((() => { const v = approvalsView(cachedApprovals(), rawActor() || { transport: 'stdio' }, null); return v ? { client_approvals: v } : {}; })()),
1153
+ ...(subkeys ? { subkeys } : {}),
939
1154
  unhandled_drops: shown.map((d) => d.doc_id),
940
1155
  unhandled_drops_more: Math.max(0, openDrops.length - shown.length),
941
1156
  retired_drops: retiredDrops.map((d) => ({ doc_id: d.doc_id, ...retirementFields(d) })),
@@ -944,7 +1159,7 @@ async function buildStartup(options = {}) {
944
1159
  // and connection; the user's name does the animating.
945
1160
  emet_line: EMET_LINE,
946
1161
  emet_line_if_unanswered: EMET_LINE_UNANSWERED,
947
- // 2026-09-26 the owner: prune may not drop the close-order tool. These two
1162
+ // 2026-09-26 Alex: prune may not drop the close-order tool. These two
948
1163
  // fields MUST precede identity/character/user so a 20k host truncate
949
1164
  // still receives them. The charter text may stay pointed; the steps may not.
950
1165
  tools_in_force: {
@@ -957,12 +1172,12 @@ async function buildStartup(options = {}) {
957
1172
  'source tag on every write'
958
1173
  ],
959
1174
  on_wrap: ['working documents', 'episodic session record', 'board', 'verbatim transcript', 'HANDOFF last one write'],
960
- // 2026-09-26 the owner (a decision record): close is blocked without receipts.
1175
+ // 2026-09-26 Alex (procedural ref 391): close is blocked without receipts.
961
1176
  confirm: 'emet_session_close with receipts for all four items and the handoff; say its speak lines in order; saved only when state is complete'
962
1177
  },
963
1178
  // Code audit 2026-09-27 (2.1): the short instructions ride up front with
964
1179
  // tools_in_force, for the same reason - a 20K cut must not take them.
965
- instructions_short: shortInstructions(),
1180
+ instructions_short: shortInstructions(gems_available),
966
1181
  session_close_protocol: CLOSE_PROTOCOL,
967
1182
  operating_discipline: DISCIPLINE_SUMMARY,
968
1183
  charter: charterPayload(charterStore ? charterStore.content : null),
@@ -984,7 +1199,7 @@ async function buildStartup(options = {}) {
984
1199
  ...retirementFields(installNotes)
985
1200
  } : null,
986
1201
  install_notes_doc_id: installDoc(),
987
- // One line each since 2026-09-27 (the owner); the full seed is one read_doc away.
1202
+ // One line each since 2026-09-27 (Alex); the full seed is one read_doc away.
988
1203
  seeds: seeds.map((s) => seedLine(s)),
989
1204
  seeds_due: seeds.filter((s) => s.due && s.retired !== true).map((s) => s.doc_id),
990
1205
  seeds_evaluated_on: today,
@@ -1006,6 +1221,9 @@ async function buildStartup(options = {}) {
1006
1221
  // the same move layers.js made for the silent meta layer. The ids are
1007
1222
  // one emet_gaps call away. A failed assessment is reported, not hidden.
1008
1223
  record_gaps: await gapCounts(),
1224
+ // Topic-page lint, counts only, on the weekly cadence. The page is a view.
1225
+ // This field is the digest. It writes nothing and it is not a record.
1226
+ page_lint: await pageLintDigest(),
1009
1227
  // The rows the board and the handoff already name. The session says them.
1010
1228
  // A section marked unread was not a table, so the document is still read.
1011
1229
  named_items: namedItemsFrom(
@@ -1025,7 +1243,9 @@ async function buildStartup(options = {}) {
1025
1243
  floor: FLOOR,
1026
1244
  floor_precedence: FLOOR_PRECEDENCE,
1027
1245
  floor_reassertion: FLOOR_REASSERTION,
1028
- instructions: readyInstructions(Boolean(character))
1246
+ instructions: readyInstructions(Boolean(character), gems_available),
1247
+ gems_available,
1248
+ gems_active
1029
1249
  };
1030
1250
  } finally {
1031
1251
  if (client) await client.close();
@@ -1107,6 +1327,11 @@ function renderUserDoc(a) {
1107
1327
  '## §3 PREFERENCES',
1108
1328
  a.user_preferences && String(a.user_preferences).trim() ? a.user_preferences : 'None stated.',
1109
1329
  '',
1330
+ '## §4 BOT-TEAM BACKUP',
1331
+ a.bot_team_backup === true ? 'yes' : 'no',
1332
+ '',
1333
+ 'Recorded at setup. Yes means follow gems/bot-team-backup/guides/BOT_TEAM_BACKUP.md. No, or leaving the question out, leaves the practice off. EMET does not copy prompts or settings itself. Never store secret values in a bot-team document.',
1334
+ '',
1110
1335
  '---',
1111
1336
  '',
1112
1337
  '*Written by the EMET setup interview. Add to it as you learn more — this document is',
@@ -1116,16 +1341,16 @@ function renderUserDoc(a) {
1116
1341
  }
1117
1342
 
1118
1343
  export async function setupComplete(answers = {}, logger = null, options = {}) {
1119
- // First-time setup is the owner's (decision 2, the owner's decision record). Stage 1
1344
+ // First-time setup is the owner's (decision 2, procedural ref 407). Stage 1
1120
1345
  // guards (2026-10-02, the reviewer's stage 1 admission, conditions S1-S2):
1121
1346
  // - refused under a configured bot tag. The tag is self-declared and
1122
1347
  // emet_initialize takes no source until stage 2, so this is inert until a
1123
- // caller declares a bot tag that the owner has configured (stage 3);
1348
+ // caller declares a bot tag that Alex has configured (stage 3);
1124
1349
  // - refused on a store that is already set up unless `reissue: true` (the owner's
1125
1350
  // answer 5): a re-run replaces the user's identity documents with new
1126
1351
  // versions, so it needs the owner's explicit word. Nothing is written
1127
1352
  // when either refusal fires.
1128
- // S1-1 (the reviewer's re-check of the first draft): EACH declared value is checked, not
1353
+ // S1-1 (the reviewer's re-check of commit-1a215d7): EACH declared value is checked, not
1129
1354
  // the first non-empty one. The write below takes answers.source_tag first, so
1130
1355
  // checking only `source` let `source: <host>` + `answers.source_tag: <bot>`
1131
1356
  // write the identity documents as the bot. The tag that would be written
@@ -1140,7 +1365,7 @@ export async function setupComplete(answers = {}, logger = null, options = {}) {
1140
1365
  throw new ValidationError(
1141
1366
  field,
1142
1367
  `First-time setup is the owner's: ${declared} is a bot tag. Stop and tell the user. Nothing was written.`
1143
- );
1368
+ , { code: 'EMET-CFG-009' });
1144
1369
  }
1145
1370
  }
1146
1371
  const missing = SETUP_INTERVIEW.filter(q => q.required && !String(answers[q.key] || '').trim())
@@ -1149,10 +1374,29 @@ export async function setupComplete(answers = {}, logger = null, options = {}) {
1149
1374
  throw new ValidationError(
1150
1375
  `Setup is missing required answers: ${missing.join(', ')}. ` +
1151
1376
  'Ask the user for them - do not supply them yourself.'
1152
- );
1377
+ , { code: 'EMET-CFG-010' });
1378
+ }
1379
+ const multi = parseMoreThanOneBot(answers.more_than_one_bot);
1380
+ if (multi === null) {
1381
+ throw new ValidationError(
1382
+ 'more_than_one_bot',
1383
+ 'Answer yes or no. Yes turns on delegated client sub-keys. No leaves them off. Leaving it out leaves them off. Do not invent the answer. Nothing was written.'
1384
+ , { code: 'EMET-CFG-011' });
1385
+ }
1386
+ const backup = parseBotTeamBackup(answers.bot_team_backup);
1387
+ if (backup === null) {
1388
+ throw new ValidationError(
1389
+ 'bot_team_backup',
1390
+ 'Answer yes or no, in your own words. Yes and Yes. record bot-team backup as on. Yes is the recommended choice. No leaves it off. Leaving it out leaves it off. A non-string is refused. Do not invent the answer. Nothing was written.'
1391
+ , { code: 'EMET-CFG-012' });
1392
+ }
1393
+ answers = { ...answers, bot_team_backup: backup };
1394
+ if (multi && !dotenvWritable(options.envFile || ENV_FILE, process.env, options.startup)) {
1395
+ throw new ValidationError('more_than_one_bot', HOSTED_SUBKEY_STEPS, { code: 'EMET-CFG-004' });
1153
1396
  }
1154
1397
 
1155
1398
  const written = [];
1399
+ let subkeys = null;
1156
1400
  let client;
1157
1401
 
1158
1402
  try {
@@ -1164,10 +1408,10 @@ export async function setupComplete(answers = {}, logger = null, options = {}) {
1164
1408
  if (pid) {
1165
1409
  const person = await getPerson(conn.db, pid);
1166
1410
  if (!person || person.role !== 'owner') {
1167
- throw new ValidationError('role', 'emet_setup_complete requires the owner. Nothing was written.');
1411
+ throw new ValidationError('role', 'emet_setup_complete requires the owner. Nothing was written.', { code: 'EMET-CFG-013' });
1168
1412
  }
1169
1413
  } else if (who.transport === 'http') {
1170
- throw new ValidationError('role', 'emet_setup_complete requires the owner. Nothing was written.');
1414
+ throw new ValidationError('role', 'emet_setup_complete requires the owner. Nothing was written.', { code: 'EMET-CFG-013' });
1171
1415
  }
1172
1416
  const docsCol = conn.db.collection(DOCS_COLLECTION);
1173
1417
  const [hasIdentity, hasUser] = await Promise.all([
@@ -1182,7 +1426,7 @@ export async function setupComplete(answers = {}, logger = null, options = {}) {
1182
1426
  'This store is already set up. Re-running setup writes new versions of the user\'s identity ' +
1183
1427
  'documents (prior versions are archived). Pass reissue: true only on the owner\'s explicit word. ' +
1184
1428
  'Nothing was written.'
1185
- );
1429
+ , { code: 'EMET-CFG-014' });
1186
1430
  }
1187
1431
  // Both writes below go through the same doors as every other write.
1188
1432
  // Until 2026-09-07 the three setup documents were written by a private
@@ -1230,6 +1474,18 @@ export async function setupComplete(answers = {}, logger = null, options = {}) {
1230
1474
  const { ensureOwnerPerson } = await import('./persons.js');
1231
1475
  const person = await ensureOwnerPerson(conn.db, { display_name: answers.user_name });
1232
1476
 
1477
+ if (multi) {
1478
+ try {
1479
+ subkeys = enableSubkeysAtFirstUse({ envFile: options.envFile || ENV_FILE, startup: options.startup });
1480
+ } catch (e) {
1481
+ const message = e.validationMessage || e.message;
1482
+ // A hosted refusal is a refusal, not a half-finished setup. It is thrown
1483
+ // before these writes; if it surfaces here, do not report it as a file error.
1484
+ if (message === HOSTED_SUBKEY_STEPS) throw e;
1485
+ subkeys = { enabled: false, turned_on: false, env_error: message };
1486
+ }
1487
+ }
1488
+
1233
1489
  return {
1234
1490
  ok: true,
1235
1491
  documents: written,
@@ -1238,12 +1494,27 @@ export async function setupComplete(answers = {}, logger = null, options = {}) {
1238
1494
  source_tag: tag,
1239
1495
  person_id: person.person_id,
1240
1496
  person_role: person.role,
1497
+ bot_team_backup: backup,
1498
+ subkeys: multi
1499
+ ? (subkeys.env_error
1500
+ ? { enabled: false, turned_on: false, env_error: subkeys.env_error }
1501
+ : {
1502
+ enabled: true,
1503
+ pepper_generated: subkeys.pepper_generated,
1504
+ pepper_version: subkeys.pepper_version,
1505
+ restart_for_owner_page: true
1506
+ })
1507
+ : { enabled: setting('SUBKEYS') === '1', turned_on: false },
1241
1508
  next_step:
1242
1509
  'Setup complete and verified. Tell the user what was recorded, in their own words, and ' +
1243
1510
  'that they can change any of it later with write_doc. If other hosts will connect to this ' +
1244
1511
  'same store, each one needs its own source tag: on a server several hosts share, leave EMET_SOURCE_TAG ' +
1245
1512
  'unset, have each host pass its tag as `source` on its writes, and register the tags in EMET_SOURCE_TAGS; ' +
1246
- 'set EMET_SOURCE_TAG only on a server one host uses. New logins will be issued as this person, not as a generic owner.'
1513
+ 'set EMET_SOURCE_TAG only on a server one host uses. New logins will be issued as this person, not as a generic owner. ' +
1514
+ subkeySetupNote(multi, subkeys) + ' ' +
1515
+ (backup
1516
+ ? 'Bot-team backup is on. Follow gems/bot-team-backup/guides/BOT_TEAM_BACKUP.md. Revise bot-team documents only when they change, and never store secret values.'
1517
+ : 'Bot-team backup stays off.')
1247
1518
  };
1248
1519
  } finally {
1249
1520
  if (client) await client.close();