@dreamforgestudiollc/emet 0.3.6 → 0.3.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/.env.example +29 -0
  2. package/CHANGELOG.md +25 -1
  3. package/README.md +9 -3
  4. package/RELEASE_NOTES-0.2.6.md +1 -1
  5. package/RELEASE_NOTES-0.3.7.md +19 -0
  6. package/docs/BOTS.md +1 -1
  7. package/docs/DEPLOY.md +14 -1
  8. package/docs/ERROR-CODES-SPEC.md +4 -0
  9. package/docs/ERROR-CODES.md +7 -0
  10. package/docs/ROADMAP.md +3 -3
  11. package/docs/SETUP.md +4 -0
  12. package/docs/SUBKEYS.md +3 -1
  13. package/docs/continuity-currency-statechart.md +34 -0
  14. package/docs/features/README.md +21 -0
  15. package/docs/features/access.md +28 -0
  16. package/docs/features/documents.md +35 -0
  17. package/docs/features/errors.md +32 -0
  18. package/docs/features/gems.md +31 -0
  19. package/docs/features/memory.md +29 -0
  20. package/docs/features/pages.md +28 -0
  21. package/docs/features/record.md +27 -0
  22. package/docs/features/search.md +27 -0
  23. package/docs/features/startup.md +29 -0
  24. package/docs/features/subkeys.md +30 -0
  25. package/docs/features/transcripts.md +33 -0
  26. package/docs/per-tag-handoff-statechart.md +147 -0
  27. package/docs/subkey-session-statechart.md +57 -0
  28. package/package.json +3 -2
  29. package/server.json +27 -2
  30. package/src/annotations.js +4 -3
  31. package/src/attribution.js +1 -1
  32. package/src/chooser.js +74 -3
  33. package/src/conformance.js +2 -0
  34. package/src/continuity-currency-statechart.js +139 -0
  35. package/src/continuity-currency.js +869 -0
  36. package/src/dispatch.js +1 -1
  37. package/src/error-codes.js +7 -0
  38. package/src/http-remote.js +27 -4
  39. package/src/index.js +1 -0
  40. package/src/pages.js +15 -0
  41. package/src/per-tag-handoff-statechart.js +264 -0
  42. package/src/per-tag-handoff.js +988 -0
  43. package/src/persons.js +16 -0
  44. package/src/session-graph.js +118 -7
  45. package/src/session.js +54 -10
  46. package/src/setup.js +22 -1
  47. package/src/startup-pages.js +13 -2
  48. package/src/subkey-lifecycle.js +105 -0
  49. package/src/subkey-session-statechart.js +253 -0
  50. package/src/subkeys.js +648 -89
  51. package/src/tools.js +157 -32
  52. package/src/version.js +1 -1
  53. package/templates/INDEX.md +1 -0
  54. package/templates/TAGHANDOFF.md +45 -0
  55. package/verification/continuity-currency/ContinuityCurrency.cfg +12 -0
  56. package/verification/continuity-currency/ContinuityCurrency.tla +239 -0
  57. package/verification/continuity-currency/tlc-output.txt +32 -0
  58. package/verification/continuity-currency/view.mjs +54 -0
  59. package/verification/per-tag-handoff/PerTagHandoff.cfg +10 -0
  60. package/verification/per-tag-handoff/PerTagHandoff.tla +191 -0
  61. package/verification/per-tag-handoff/StampCounter.cfg +10 -0
  62. package/verification/per-tag-handoff/out/report.md +6 -0
  63. package/verification/per-tag-handoff/out-counter/chart.mmd +30 -0
  64. package/verification/per-tag-handoff/out-counter/report.md +15 -0
  65. package/verification/per-tag-handoff/out-counter/tlc.out +130 -0
  66. package/verification/per-tag-handoff/split/PerTagConflict.cfg +6 -0
  67. package/verification/per-tag-handoff/split/PerTagConflict.tla +104 -0
  68. package/verification/per-tag-handoff/split/PerTagTime.cfg +8 -0
  69. package/verification/per-tag-handoff/split/PerTagTime.tla +100 -0
  70. package/verification/per-tag-handoff/split/conflict-chart.mmd +47 -0
  71. package/verification/per-tag-handoff/split/conflict-report.md +8 -0
  72. package/verification/per-tag-handoff/split/conflict-tlc.txt +19 -0
  73. package/verification/per-tag-handoff/split/conflict-view.mjs +34 -0
  74. package/verification/per-tag-handoff/split/time-chart.mmd +44 -0
  75. package/verification/per-tag-handoff/split/time-report.md +8 -0
  76. package/verification/per-tag-handoff/split/time-tlc.txt +19 -0
  77. package/verification/per-tag-handoff/split/time-view.mjs +33 -0
  78. package/verification/per-tag-handoff/tlc-output.txt +19 -0
  79. package/verification/per-tag-handoff/v1-draft/PerTagHandoff.cfg +5 -0
  80. package/verification/per-tag-handoff/v1-draft/PerTagHandoff.tla +94 -0
  81. package/verification/per-tag-handoff/v1-draft/out/chart.mmd +37 -0
  82. package/verification/per-tag-handoff/v1-draft/out/report.md +7 -0
  83. package/verification/per-tag-handoff/v1-draft/out/tlc.out +19 -0
  84. package/verification/per-tag-handoff/v1-draft/view.mjs +20 -0
  85. package/verification/per-tag-handoff/view.mjs +31 -0
  86. package/verification/subkey-session/SubkeySession.cfg +11 -0
  87. package/verification/subkey-session/SubkeySession.tla +254 -0
  88. package/verification/subkey-session/tlc-output.txt +13 -0
@@ -0,0 +1,253 @@
1
+ /**
2
+ * Sub-key session statechart.
3
+ *
4
+ * One key, one session slot. Renewal and reclaim replace that slot.
5
+ * A handle with no key does not mint the next session.
6
+ * The picture is docs/subkey-session-statechart.md.
7
+ * The model is verification/subkey-session/SubkeySession.tla.
8
+ */
9
+
10
+ export const SUBKEY_SESSION_MERMAID = `stateDiagram-v2
11
+ [*] --> opening
12
+ opening --> live: open commits
13
+ opening --> ended: open lost
14
+ live --> renewal_offered: last hour, handle still valid
15
+ renewal_offered --> live: renew with the key and the handle
16
+ live --> live: renew with the key and the handle
17
+ live --> expired: handle expires
18
+ renewal_offered --> expired: handle expires
19
+ expired --> live: renew with the key and the handle, inside grace
20
+ expired --> unwrapped: chat, no wrap-up, key still required to open
21
+ unwrapped --> live: same key opens the next session
22
+ live --> closed: owner, or same key reclaim, or a clean close
23
+ ended --> auto_closed: sweep
24
+ expired --> auto_closed: past grace, sweep
25
+ unwrapped --> auto_closed: past grace, sweep
26
+ opening --> auto_closed: past grace, sweep
27
+ live --> revoked: revoke
28
+ renewal_offered --> revoked: revoke
29
+ closed --> [*]
30
+ auto_closed --> [*]
31
+ revoked --> [*]`;
32
+
33
+ export const SUBKEY_SESSION_STEPS = Object.freeze([
34
+ 'A session opens into one live slot for its key. A second open while that slot is still in its 12 hours is a collision for a bot key.',
35
+ 'Inside the last hour the server asks the caller to wrap up and open again with the sub-key and the current handle. The handle still works. The server does not mint a handle from that call.',
36
+ 'A renewal presents the sub-key and the current handle. The old session closes into the new one in the same write. One live session remains. The new row records the previous open.',
37
+ 'After expiry, the grace window still accepts that pair. The handle alone does not mint a session.',
38
+ 'A chat key is the kind the owner stored. A chat whose handle expired with no wrap-up record is marked unwrapped, and the next open with the key is still allowed. The reply tells the user to go back and wrap that chat up.',
39
+ 'A wrap-up record for that tag, written between the handle and now, lets the old session close into the new one.',
40
+ 'The owner, or a new open with the same key, carry-forward closes a stranded session of that key. Another key does not.',
41
+ 'Past the grace window, or when the link is already ended, the sweep records auto_closed. The row and the transcript stay. A status read is not refused and does not write handle_expired.'
42
+ ]);
43
+
44
+ const SESS = new Set([
45
+ 'opening', 'live', 'renewal_offered', 'ended', 'expired', 'unwrapped', 'closed', 'auto_closed', 'revoked'
46
+ ]);
47
+ const PHASE = new Set(['fresh', 'window', 'grace', 'beyond']);
48
+ const CLOSED = new Set(['closed', 'auto_closed', 'revoked']);
49
+ const ORDER = ['fresh', 'window', 'grace', 'beyond'];
50
+
51
+ function same(state, extra) {
52
+ return { ...state, ...extra };
53
+ }
54
+
55
+ /** A step that changes the session record. `store` counts those writes. */
56
+ function wrote(state, extra) {
57
+ const store = state.store || 0;
58
+ return { ...state, ...extra, store: store + 1, prevStore: store, act: 'write' };
59
+ }
60
+
61
+ /** A read. The session record and the store counter stay where they are. */
62
+ function read(state, act) {
63
+ const store = state.store || 0;
64
+ return { ...state, store, prevStore: store, act };
65
+ }
66
+
67
+ /**
68
+ * One step. An event that cannot happen returns null.
69
+ * `credential` is `key` for renew and reclaim, `handle` for a bare handle, `foreign` for another tag.
70
+ */
71
+ export function subkeySessionStep(state, event, credential = 'key') {
72
+ if (!state || !SESS.has(state.sess) || !PHASE.has(state.phase)) return null;
73
+ if (state.kind !== 'bot' && state.kind !== 'chat') return null;
74
+ const next = { ...state };
75
+
76
+ if (event === 'rest') {
77
+ if (!CLOSED.has(state.sess)) return null;
78
+ return same(state, {});
79
+ }
80
+ if (event === 'status') return read(state, 'status');
81
+ if (CLOSED.has(state.sess)) return null;
82
+
83
+ if (event === 'commit') {
84
+ if (state.sess !== 'opening' || (state.phase !== 'fresh' && state.phase !== 'window')) return null;
85
+ return wrote(state, { sess: 'live', live: 1 });
86
+ }
87
+ if (event === 'lose') {
88
+ if (state.sess !== 'opening') return null;
89
+ return wrote(state, { sess: 'ended', live: 0 });
90
+ }
91
+ if (event === 'offer') {
92
+ if (state.sess !== 'live' || state.phase !== 'window' || state.live !== 1) return null;
93
+ return wrote(state, { sess: 'renewal_offered' });
94
+ }
95
+ if (event === 'advance') {
96
+ const i = ORDER.indexOf(state.phase);
97
+ if (i < 0 || i === ORDER.length - 1) return null;
98
+ const phase = ORDER[i + 1];
99
+ if ((state.sess === 'live' || state.sess === 'renewal_offered') && (phase === 'grace' || phase === 'beyond')) {
100
+ return wrote(state, { phase, sess: 'expired', live: 0 });
101
+ }
102
+ return wrote(state, { phase });
103
+ }
104
+ if (event === 'renew') {
105
+ if (credential !== 'key') return null;
106
+ if (state.gen >= 1) return null;
107
+ if (state.phase !== 'window' && state.phase !== 'grace') return null;
108
+ if (!['live', 'renewal_offered', 'expired'].includes(state.sess)) return null;
109
+ return wrote(state, {
110
+ sess: 'live', phase: 'fresh', gen: state.gen + 1, live: 1,
111
+ prevClosed: true, closedBy: 'same', bareMint: false
112
+ });
113
+ }
114
+ if (event === 'reclaim') {
115
+ if (credential !== 'key') return null;
116
+ if (state.reclaims >= 1) return null;
117
+ if (state.sess === 'opening') return null;
118
+ const stranded = ['ended', 'expired', 'unwrapped'].includes(state.sess) || state.phase === 'grace' || state.phase === 'beyond';
119
+ if (state.kind !== 'chat' && !stranded) return null;
120
+ const chatClean = state.kind === 'chat' && state.wrap && state.sess !== 'ended';
121
+ return wrote(state, {
122
+ sess: 'live', phase: 'fresh', live: 1, reclaims: state.reclaims + 1,
123
+ prevClosed: chatClean || state.kind !== 'chat' || state.wrap || state.sess === 'ended' || state.phase === 'beyond',
124
+ closedBy: 'same', bareMint: false
125
+ });
126
+ }
127
+ if (event === 'unwrap') {
128
+ if (state.kind !== 'chat' || state.wrap || state.phase !== 'grace' || state.sess !== 'expired') return null;
129
+ return wrote(state, { sess: 'unwrapped', live: 0, bareMint: false });
130
+ }
131
+ if (event === 'owner_close') {
132
+ return wrote(state, { sess: 'closed', live: 0, closedBy: 'owner', prevClosed: true });
133
+ }
134
+ if (event === 'sweep') {
135
+ if (state.phase !== 'beyond' && state.sess !== 'ended') return null;
136
+ if (state.sess === 'ended' || state.phase === 'beyond') {
137
+ return wrote(state, { sess: 'auto_closed', live: 0, closedBy: 'sweep', prevClosed: true });
138
+ }
139
+ return null;
140
+ }
141
+ if (event === 'revoke') {
142
+ return wrote(state, { sess: 'revoked', live: 0, closedBy: 'owner' });
143
+ }
144
+ if (event === 'bare_handle') {
145
+ if (credential !== 'handle') return null;
146
+ return read(state, 'bare');
147
+ }
148
+ if (event === 'foreign_close') {
149
+ if (credential !== 'foreign') return null;
150
+ return same(next, {});
151
+ }
152
+ if (event === 'collision') {
153
+ if (state.kind !== 'bot' || !['live', 'renewal_offered'].includes(state.sess)) return null;
154
+ if (state.phase !== 'fresh' && state.phase !== 'window') return null;
155
+ return same(next, {});
156
+ }
157
+ return null;
158
+ }
159
+
160
+ export function initialSubkeySessions() {
161
+ const rows = [];
162
+ for (const kind of ['bot', 'chat']) {
163
+ for (const wrap of [false, true]) {
164
+ rows.push({
165
+ sess: 'opening', phase: 'fresh', kind, wrap, gen: 0, live: 0,
166
+ reclaims: 0, bareMint: false, closedBy: 'none', prevClosed: false,
167
+ store: 0, prevStore: 0, act: 'init'
168
+ });
169
+ }
170
+ }
171
+ return rows;
172
+ }
173
+
174
+ const EVENTS = [
175
+ 'commit', 'lose', 'offer', 'advance', 'renew', 'reclaim', 'unwrap',
176
+ 'owner_close', 'sweep', 'revoke', 'bare_handle', 'status', 'foreign_close', 'collision', 'rest'
177
+ ];
178
+
179
+ function credFor(event) {
180
+ if (event === 'bare_handle') return 'handle';
181
+ if (event === 'foreign_close') return 'foreign';
182
+ return 'key';
183
+ }
184
+
185
+ function keyOf(state) {
186
+ return [state.sess, state.phase, state.kind, state.wrap, state.gen, state.live, state.reclaims, state.bareMint, state.closedBy, state.prevClosed].join('|');
187
+ }
188
+
189
+ /**
190
+ * Every reachable slot. `stranded` is a non-closed state from which
191
+ * commit, lose, advance, and sweep cannot reach a closed state.
192
+ */
193
+ export function auditSubkeySessions() {
194
+ const start = initialSubkeySessions();
195
+ const seen = new Map();
196
+ const queue = [];
197
+ for (const row of start) {
198
+ seen.set(keyOf(row), row);
199
+ queue.push(row);
200
+ }
201
+ while (queue.length) {
202
+ const row = queue.shift();
203
+ for (const event of EVENTS) {
204
+ const step = subkeySessionStep(row, event, credFor(event));
205
+ if (!step) continue;
206
+ const id = keyOf(step);
207
+ if (seen.has(id)) continue;
208
+ seen.set(id, step);
209
+ queue.push(step);
210
+ }
211
+ }
212
+ const rows = [...seen.values()];
213
+ const problems = [];
214
+ for (const row of rows) {
215
+ if (row.live > 1) problems.push({ rule: 'live', row });
216
+ if (row.bareMint) problems.push({ rule: 'bare', row });
217
+ if (row.closedBy === 'foreign') problems.push({ rule: 'foreign', row });
218
+ if ((row.sess === 'closed' || row.sess === 'auto_closed') && !['same', 'owner', 'sweep'].includes(row.closedBy)) {
219
+ problems.push({ rule: 'closer', row });
220
+ }
221
+ if (row.sess === 'unwrapped' && row.live !== 0) problems.push({ rule: 'unwrapped', row });
222
+ const status = subkeySessionStep(row, 'status', 'key');
223
+ if (!status || status.act !== 'status' || status.store !== row.store || status.sess !== row.sess || status.prevStore !== status.store) {
224
+ problems.push({ rule: 'status-write', row });
225
+ }
226
+ const bare = subkeySessionStep(row, 'bare_handle', 'handle');
227
+ if (bare && (bare.act !== 'bare' || bare.store !== row.store || bare.sess !== row.sess || bare.live !== row.live)) {
228
+ problems.push({ rule: 'bare-write', row });
229
+ }
230
+ }
231
+ const progress = new Set(['commit', 'lose', 'advance', 'sweep']);
232
+ const stranded = [];
233
+ for (const row of rows) {
234
+ if (['closed', 'auto_closed', 'revoked'].includes(row.sess)) continue;
235
+ const reach = new Map([[keyOf(row), row]]);
236
+ const q = [row];
237
+ let settled = false;
238
+ while (q.length) {
239
+ const cur = q.shift();
240
+ if (['closed', 'auto_closed', 'revoked'].includes(cur.sess)) { settled = true; break; }
241
+ for (const event of progress) {
242
+ const step = subkeySessionStep(cur, event, 'key');
243
+ if (!step) continue;
244
+ const id = keyOf(step);
245
+ if (reach.has(id)) continue;
246
+ reach.set(id, step);
247
+ q.push(step);
248
+ }
249
+ }
250
+ if (!settled) stranded.push(row);
251
+ }
252
+ return { count: rows.length, problems, stranded };
253
+ }