@mostra/runtime 0.0.0-stage → 0.1.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.
- package/LICENSE +202 -0
- package/README.md +39 -2
- package/dist/bin.d.ts +1 -0
- package/dist/bin.js +236 -0
- package/dist/bin.js.map +1 -0
- package/dist/builder/child/main.d.ts +1 -0
- package/dist/builder/child/main.js +1408 -0
- package/dist/builder/child/main.js.map +1 -0
- package/dist/child-xrHmytks.js +49 -0
- package/dist/child-xrHmytks.js.map +1 -0
- package/dist/deps/child/install.d.ts +1 -0
- package/dist/deps/child/install.js +33 -0
- package/dist/deps/child/install.js.map +1 -0
- package/dist/index.d.ts +221 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +3 -0
- package/dist/instance-D7_UVdoN.js +15752 -0
- package/dist/instance-D7_UVdoN.js.map +1 -0
- package/dist/types-NjNy7gXX.js +57 -0
- package/dist/types-NjNy7gXX.js.map +1 -0
- package/package.json +87 -3
- package/src/actions/index.ts +622 -0
- package/src/addressing/index.ts +281 -0
- package/src/bin.ts +240 -0
- package/src/builder/child/dev.ts +383 -0
- package/src/builder/child/fields.ts +363 -0
- package/src/builder/child/main.ts +47 -0
- package/src/builder/child/plugins.ts +195 -0
- package/src/builder/child/scan.ts +459 -0
- package/src/builder/child/spa.ts +348 -0
- package/src/builder/coverage.ts +72 -0
- package/src/builder/index.ts +406 -0
- package/src/builder/types.ts +180 -0
- package/src/deps/child/install.ts +30 -0
- package/src/deps/index.ts +918 -0
- package/src/deps/installer.ts +321 -0
- package/src/deps/lock.ts +82 -0
- package/src/deps/scan.ts +266 -0
- package/src/deps/specifier.ts +64 -0
- package/src/deps/warm.ts +57 -0
- package/src/dev/index.ts +518 -0
- package/src/faults.ts +65 -0
- package/src/gate.ts +55 -0
- package/src/gateway/actions.ts +268 -0
- package/src/gateway/browser.ts +650 -0
- package/src/gateway/capabilities.ts +739 -0
- package/src/gateway/controls.ts +91 -0
- package/src/gateway/dev.ts +119 -0
- package/src/gateway/http.ts +229 -0
- package/src/gateway/index.ts +1209 -0
- package/src/gateway/integrity.ts +117 -0
- package/src/gateway/listener.ts +217 -0
- package/src/gateway/routes.ts +197 -0
- package/src/gateway/serve.ts +138 -0
- package/src/gc/index.ts +451 -0
- package/src/home/acquire.ts +276 -0
- package/src/home/index.ts +16 -0
- package/src/home/paths.ts +192 -0
- package/src/home/platform.ts +34 -0
- package/src/home/record.ts +76 -0
- package/src/home/settings.ts +113 -0
- package/src/index.ts +30 -0
- package/src/instance/index.ts +942 -0
- package/src/interaction/ephemeral.ts +300 -0
- package/src/interaction/events.ts +355 -0
- package/src/interaction/fields.ts +392 -0
- package/src/interaction/index.ts +1009 -0
- package/src/interaction/outbox.ts +493 -0
- package/src/interaction/policy.ts +26 -0
- package/src/interaction/results.ts +341 -0
- package/src/interaction/runs.ts +313 -0
- package/src/interaction/signals.ts +120 -0
- package/src/interaction/submissions.ts +585 -0
- package/src/interaction/subscriptions.ts +258 -0
- package/src/interaction/viewers.ts +173 -0
- package/src/interaction/wait.ts +201 -0
- package/src/ledger/index.ts +442 -0
- package/src/ledger/migrations.ts +583 -0
- package/src/ledger/requests.ts +105 -0
- package/src/ledger/types.ts +28 -0
- package/src/live/index.ts +573 -0
- package/src/log.ts +316 -0
- package/src/processes/child.ts +67 -0
- package/src/processes/environment.ts +64 -0
- package/src/processes/identity.ts +191 -0
- package/src/processes/index.ts +19 -0
- package/src/processes/manager.ts +543 -0
- package/src/protocol-server/client.ts +94 -0
- package/src/protocol-server/index.ts +91 -0
- package/src/protocol-server/server.ts +509 -0
- package/src/protocol-server/streams.ts +81 -0
- package/src/publish/checks.ts +92 -0
- package/src/publish/digest.ts +87 -0
- package/src/publish/index.ts +23 -0
- package/src/publish/manifest.ts +409 -0
- package/src/publish/methods.ts +96 -0
- package/src/publish/publisher.ts +913 -0
- package/src/publish/source.ts +272 -0
- package/src/publish/tar.ts +110 -0
- package/src/registry/index.ts +481 -0
- package/src/registry/store.ts +136 -0
- package/src/secrets/index.ts +223 -0
- package/src/service/idle.ts +64 -0
- package/src/service/index.ts +3 -0
- package/src/service/unit.ts +250 -0
- package/src/verify/fields.ts +125 -0
- package/src/verify/index.ts +913 -0
- package/src/verify/regression.ts +157 -0
- package/src/verify/runner.ts +230 -0
- package/src/verify/sandbox.ts +407 -0
- package/src/verify/typecheck.ts +371 -0
- package/src/workers/index.ts +17 -0
- package/src/workers/launcher.ts +260 -0
- package/src/workers/pool.ts +708 -0
|
@@ -0,0 +1,300 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Ephemeral traffic to pages (D47, D63, LL-04): run progress, log lines and result items, and live
|
|
3
|
+
* values. None of it is an event: it reaches the views that asked for it within the last minute
|
|
4
|
+
* (a run they started or attached to, a live source they read) and is lost by anyone who isn't
|
|
5
|
+
* listening, because what it reports is also readable on demand (`runs/attach`, `live`). A view's
|
|
6
|
+
* open event stream hears it at once; a view that long-polls collects it in a bounded queue
|
|
7
|
+
* between polls.
|
|
8
|
+
*/
|
|
9
|
+
import type { EphemeralMessage } from "@mostra/protocol";
|
|
10
|
+
|
|
11
|
+
/** How long a view's interest in a run or a live source lasts without being renewed. */
|
|
12
|
+
export const INTEREST_LEASE_MS: number = 60_000;
|
|
13
|
+
|
|
14
|
+
/** The most messages a polling view keeps between polls; older ones are dropped. */
|
|
15
|
+
const POLL_QUEUE_MAX = 1000;
|
|
16
|
+
|
|
17
|
+
/** What a view listens to. */
|
|
18
|
+
interface ViewInterest {
|
|
19
|
+
readonly artifactId: string;
|
|
20
|
+
readonly runs: Map<string, number>;
|
|
21
|
+
readonly live: Map<string, { until: number; window?: number }>;
|
|
22
|
+
readonly listeners: Set<(message: EphemeralMessage) => void>;
|
|
23
|
+
queue?: EphemeralMessage[];
|
|
24
|
+
queueUntil?: number;
|
|
25
|
+
wake?: () => void;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
type RunMessage = Extract<EphemeralMessage, { kind: "run" }>;
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* Adds `message` to a view's queue of messages not yet sent, coalesced (D130, FAILURE_MODEL §6;
|
|
32
|
+
* Opus review 12), so a fast source can't make a slow reader fall behind:
|
|
33
|
+
* - a live value in latest mode replaces the values of its source still queued: the page shows
|
|
34
|
+
* only the newest (append mode keeps every value, for the ring);
|
|
35
|
+
* - a run's delta that continues the one queued for the run merges into it, losing nothing.
|
|
36
|
+
*/
|
|
37
|
+
function coalesceInto(
|
|
38
|
+
view: ViewInterest,
|
|
39
|
+
queue: EphemeralMessage[],
|
|
40
|
+
message: EphemeralMessage,
|
|
41
|
+
): void {
|
|
42
|
+
if (message.kind === "live") {
|
|
43
|
+
const latestMode = view.live.get(message.live.key)?.window === undefined;
|
|
44
|
+
if (latestMode && message.live.value !== undefined) {
|
|
45
|
+
for (let index = queue.length - 1; index >= 0; index--) {
|
|
46
|
+
const queued = queue[index] as EphemeralMessage;
|
|
47
|
+
if (
|
|
48
|
+
queued.kind === "live" &&
|
|
49
|
+
queued.live.key === message.live.key &&
|
|
50
|
+
queued.live.value !== undefined
|
|
51
|
+
) {
|
|
52
|
+
queue.splice(index, 1);
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
queue.push(message);
|
|
57
|
+
return;
|
|
58
|
+
}
|
|
59
|
+
const delta = message.run;
|
|
60
|
+
for (let index = queue.length - 1; index >= 0; index--) {
|
|
61
|
+
const queued = queue[index] as EphemeralMessage;
|
|
62
|
+
if (queued.kind !== "run" || queued.run.runId !== delta.runId) continue;
|
|
63
|
+
const prior = queued.run;
|
|
64
|
+
if (
|
|
65
|
+
delta.logFrom === prior.logFrom + prior.log.length &&
|
|
66
|
+
delta.batchFrom === prior.batchFrom + prior.batches.length
|
|
67
|
+
) {
|
|
68
|
+
const merged: RunMessage = {
|
|
69
|
+
kind: "run",
|
|
70
|
+
run: {
|
|
71
|
+
...prior,
|
|
72
|
+
...delta,
|
|
73
|
+
logFrom: prior.logFrom,
|
|
74
|
+
log: [...prior.log, ...delta.log],
|
|
75
|
+
batchFrom: prior.batchFrom,
|
|
76
|
+
batches: [...prior.batches, ...delta.batches],
|
|
77
|
+
...((delta.progress ?? prior.progress)
|
|
78
|
+
? { progress: delta.progress ?? prior.progress }
|
|
79
|
+
: {}),
|
|
80
|
+
},
|
|
81
|
+
};
|
|
82
|
+
queue[index] = merged;
|
|
83
|
+
return;
|
|
84
|
+
}
|
|
85
|
+
break;
|
|
86
|
+
}
|
|
87
|
+
queue.push(message);
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** A live source some view, host or `always` keeps alive. */
|
|
91
|
+
export interface LiveInterest {
|
|
92
|
+
readonly artifactId: string;
|
|
93
|
+
readonly key: string;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/** The bus. */
|
|
97
|
+
export interface EphemeralBus {
|
|
98
|
+
/**
|
|
99
|
+
* Adds `message` to `queue`, a reader's messages not yet sent, coalescing it with what the
|
|
100
|
+
* queue holds for the same source or run as the view's interest allows.
|
|
101
|
+
*/
|
|
102
|
+
coalesce(
|
|
103
|
+
artifactId: string,
|
|
104
|
+
viewId: string,
|
|
105
|
+
queue: EphemeralMessage[],
|
|
106
|
+
message: EphemeralMessage,
|
|
107
|
+
): void;
|
|
108
|
+
/** The view follows these runs for the next minute. */
|
|
109
|
+
attachRuns(artifactId: string, viewId: string, runIds: readonly string[]): void;
|
|
110
|
+
/** The view reads these live sources for the next minute. */
|
|
111
|
+
watchLive(
|
|
112
|
+
artifactId: string,
|
|
113
|
+
viewId: string,
|
|
114
|
+
keys: readonly { readonly key: string; readonly window?: number }[],
|
|
115
|
+
): void;
|
|
116
|
+
/** Sends a run's change to every view following it. */
|
|
117
|
+
publishRun(artifactId: string, message: Extract<EphemeralMessage, { kind: "run" }>): void;
|
|
118
|
+
/** Sends a live update to every view reading the source. */
|
|
119
|
+
publishLive(artifactId: string, message: Extract<EphemeralMessage, { kind: "live" }>): void;
|
|
120
|
+
/** Hears the view's messages as they come (an open event stream); returns the stop. */
|
|
121
|
+
listen(
|
|
122
|
+
artifactId: string,
|
|
123
|
+
viewId: string,
|
|
124
|
+
listener: (message: EphemeralMessage) => void,
|
|
125
|
+
): () => void;
|
|
126
|
+
/** Takes what the view collected since its last poll, starting its queue on the first. */
|
|
127
|
+
drain(artifactId: string, viewId: string): EphemeralMessage[];
|
|
128
|
+
/** Resolves when the polling view has something, or after `ms`. */
|
|
129
|
+
wait(artifactId: string, viewId: string, ms: number, signal?: AbortSignal): Promise<void>;
|
|
130
|
+
/** The live sources views read now. */
|
|
131
|
+
liveInterest(): LiveInterest[];
|
|
132
|
+
/** Hears every change of {@link liveInterest}; returns the stop. */
|
|
133
|
+
onLiveInterest(listener: () => void): () => void;
|
|
134
|
+
/** How many views listen or poll now: the daemon stays while any do (D62). */
|
|
135
|
+
activeViews(): number;
|
|
136
|
+
/** Stops the lease timer. */
|
|
137
|
+
close(): void;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/** Creates the bus. */
|
|
141
|
+
export function createEphemeralBus(
|
|
142
|
+
options: { readonly now?: () => number; readonly leaseMs?: number } = {},
|
|
143
|
+
): EphemeralBus {
|
|
144
|
+
const now = options.now ?? Date.now;
|
|
145
|
+
const lease = options.leaseMs ?? INTEREST_LEASE_MS;
|
|
146
|
+
const views = new Map<string, ViewInterest>();
|
|
147
|
+
const interestListeners = new Set<() => void>();
|
|
148
|
+
let lastInterest = "";
|
|
149
|
+
|
|
150
|
+
const viewOf = (artifactId: string, viewId: string): ViewInterest => {
|
|
151
|
+
let view = views.get(viewId);
|
|
152
|
+
if (!view || view.artifactId !== artifactId) {
|
|
153
|
+
view = { artifactId, runs: new Map(), live: new Map(), listeners: new Set() };
|
|
154
|
+
views.set(viewId, view);
|
|
155
|
+
}
|
|
156
|
+
return view;
|
|
157
|
+
};
|
|
158
|
+
|
|
159
|
+
const interestKey = (): string =>
|
|
160
|
+
[...new Set(currentInterest().map((entry) => `${entry.artifactId}\u0000${entry.key}`))]
|
|
161
|
+
.sort()
|
|
162
|
+
.join("\u0001");
|
|
163
|
+
|
|
164
|
+
const currentInterest = (): LiveInterest[] => {
|
|
165
|
+
const at = now();
|
|
166
|
+
const out: LiveInterest[] = [];
|
|
167
|
+
for (const view of views.values()) {
|
|
168
|
+
for (const [key, lease] of view.live) {
|
|
169
|
+
if (lease.until > at) out.push({ artifactId: view.artifactId, key });
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
return out;
|
|
173
|
+
};
|
|
174
|
+
|
|
175
|
+
const interestChanged = (): void => {
|
|
176
|
+
const next = interestKey();
|
|
177
|
+
if (next === lastInterest) return;
|
|
178
|
+
lastInterest = next;
|
|
179
|
+
for (const listener of interestListeners) listener();
|
|
180
|
+
};
|
|
181
|
+
|
|
182
|
+
const deliver = (view: ViewInterest, message: EphemeralMessage): void => {
|
|
183
|
+
for (const listener of view.listeners) listener(message);
|
|
184
|
+
if (view.queue && (view.queueUntil ?? 0) > now()) {
|
|
185
|
+
coalesceInto(view, view.queue, message);
|
|
186
|
+
if (view.queue.length > POLL_QUEUE_MAX)
|
|
187
|
+
view.queue.splice(0, view.queue.length - POLL_QUEUE_MAX);
|
|
188
|
+
view.wake?.();
|
|
189
|
+
}
|
|
190
|
+
};
|
|
191
|
+
|
|
192
|
+
// Expired leases end; views with nothing left are forgotten.
|
|
193
|
+
const sweep = setInterval(
|
|
194
|
+
() => {
|
|
195
|
+
const at = now();
|
|
196
|
+
for (const [viewId, view] of views) {
|
|
197
|
+
for (const [runId, until] of view.runs) if (until <= at) view.runs.delete(runId);
|
|
198
|
+
for (const [key, lease] of view.live) if (lease.until <= at) view.live.delete(key);
|
|
199
|
+
if (view.queue && (view.queueUntil ?? 0) <= at) {
|
|
200
|
+
delete view.queue;
|
|
201
|
+
delete view.queueUntil;
|
|
202
|
+
}
|
|
203
|
+
if (
|
|
204
|
+
view.runs.size === 0 &&
|
|
205
|
+
view.live.size === 0 &&
|
|
206
|
+
view.listeners.size === 0 &&
|
|
207
|
+
!view.queue
|
|
208
|
+
) {
|
|
209
|
+
views.delete(viewId);
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
interestChanged();
|
|
213
|
+
},
|
|
214
|
+
Math.min(5_000, Math.max(100, lease / 4)),
|
|
215
|
+
);
|
|
216
|
+
sweep.unref?.();
|
|
217
|
+
|
|
218
|
+
return {
|
|
219
|
+
coalesce(artifactId, viewId, queue, message) {
|
|
220
|
+
coalesceInto(viewOf(artifactId, viewId), queue, message);
|
|
221
|
+
},
|
|
222
|
+
attachRuns(artifactId, viewId, runIds) {
|
|
223
|
+
const view = viewOf(artifactId, viewId);
|
|
224
|
+
const until = now() + lease;
|
|
225
|
+
for (const runId of runIds) view.runs.set(runId, until);
|
|
226
|
+
},
|
|
227
|
+
watchLive(artifactId, viewId, keys) {
|
|
228
|
+
const view = viewOf(artifactId, viewId);
|
|
229
|
+
const until = now() + lease;
|
|
230
|
+
for (const entry of keys) {
|
|
231
|
+
view.live.set(entry.key, {
|
|
232
|
+
until,
|
|
233
|
+
...(entry.window === undefined ? {} : { window: entry.window }),
|
|
234
|
+
});
|
|
235
|
+
}
|
|
236
|
+
interestChanged();
|
|
237
|
+
},
|
|
238
|
+
publishRun(artifactId, message) {
|
|
239
|
+
const at = now();
|
|
240
|
+
for (const view of views.values()) {
|
|
241
|
+
if (view.artifactId !== artifactId) continue;
|
|
242
|
+
if ((view.runs.get(message.run.runId) ?? 0) > at) deliver(view, message);
|
|
243
|
+
}
|
|
244
|
+
},
|
|
245
|
+
publishLive(artifactId, message) {
|
|
246
|
+
const at = now();
|
|
247
|
+
for (const view of views.values()) {
|
|
248
|
+
if (view.artifactId !== artifactId) continue;
|
|
249
|
+
if ((view.live.get(message.live.key)?.until ?? 0) > at) deliver(view, message);
|
|
250
|
+
}
|
|
251
|
+
},
|
|
252
|
+
listen(artifactId, viewId, listener) {
|
|
253
|
+
const view = viewOf(artifactId, viewId);
|
|
254
|
+
view.listeners.add(listener);
|
|
255
|
+
return () => {
|
|
256
|
+
view.listeners.delete(listener);
|
|
257
|
+
};
|
|
258
|
+
},
|
|
259
|
+
drain(artifactId, viewId) {
|
|
260
|
+
const view = viewOf(artifactId, viewId);
|
|
261
|
+
const taken = view.queue ?? [];
|
|
262
|
+
view.queue = [];
|
|
263
|
+
view.queueUntil = now() + lease;
|
|
264
|
+
return taken;
|
|
265
|
+
},
|
|
266
|
+
wait(artifactId, viewId, ms, signal) {
|
|
267
|
+
const view = viewOf(artifactId, viewId);
|
|
268
|
+
if (view.queue && view.queue.length > 0) return Promise.resolve();
|
|
269
|
+
return new Promise((resolve) => {
|
|
270
|
+
const done = (): void => {
|
|
271
|
+
clearTimeout(timer);
|
|
272
|
+
signal?.removeEventListener("abort", done);
|
|
273
|
+
if (view.wake === done) delete view.wake;
|
|
274
|
+
resolve();
|
|
275
|
+
};
|
|
276
|
+
const timer = setTimeout(done, ms);
|
|
277
|
+
signal?.addEventListener("abort", done, { once: true });
|
|
278
|
+
view.wake = done;
|
|
279
|
+
});
|
|
280
|
+
},
|
|
281
|
+
liveInterest: currentInterest,
|
|
282
|
+
onLiveInterest(listener) {
|
|
283
|
+
interestListeners.add(listener);
|
|
284
|
+
return () => {
|
|
285
|
+
interestListeners.delete(listener);
|
|
286
|
+
};
|
|
287
|
+
},
|
|
288
|
+
activeViews() {
|
|
289
|
+
const at = now();
|
|
290
|
+
let count = 0;
|
|
291
|
+
for (const view of views.values()) {
|
|
292
|
+
if (view.listeners.size > 0 || (view.queueUntil ?? 0) > at) count += 1;
|
|
293
|
+
}
|
|
294
|
+
return count;
|
|
295
|
+
},
|
|
296
|
+
close() {
|
|
297
|
+
clearInterval(sweep);
|
|
298
|
+
},
|
|
299
|
+
};
|
|
300
|
+
}
|
|
@@ -0,0 +1,355 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The event log (IN-08, DATA_MODEL §3, §4): every durable change appends one event in the same
|
|
3
|
+
* ledger transaction as the change, with a home-wide cursor and a per-artifact sequence. Readers
|
|
4
|
+
* take events after a cursor, in cursor order, through one filter; since the supervisor is the
|
|
5
|
+
* only writer and every commit is serialized, a reader can never see a later cursor before an
|
|
6
|
+
* earlier one commits, so reading on from the last cursor never skips an event.
|
|
7
|
+
*
|
|
8
|
+
* ```ts
|
|
9
|
+
* ledger.write((db) => {
|
|
10
|
+
* db.run("INSERT INTO version …");
|
|
11
|
+
* const cursor = appendEvent(db, { artifactId, type: "version.published", payload: { … } });
|
|
12
|
+
* });
|
|
13
|
+
* const { events, cursor } = ledger.read((db) => readEvents(db, { filter, after: "41" }));
|
|
14
|
+
* ```
|
|
15
|
+
*/
|
|
16
|
+
import {
|
|
17
|
+
type Actor,
|
|
18
|
+
type Cursor,
|
|
19
|
+
createDiagnostic,
|
|
20
|
+
type Diagnostic,
|
|
21
|
+
type EventFilter,
|
|
22
|
+
type EventRecord,
|
|
23
|
+
RpcError,
|
|
24
|
+
} from "@mostra/protocol";
|
|
25
|
+
import type { LedgerDb } from "../ledger/index.ts";
|
|
26
|
+
|
|
27
|
+
/** Who caused an event (DATA_MODEL §4). */
|
|
28
|
+
export type EventActor = Actor;
|
|
29
|
+
|
|
30
|
+
/** One event to append. */
|
|
31
|
+
export interface NewEvent {
|
|
32
|
+
/** The artifact the event belongs to, or `null` for a home-wide event. */
|
|
33
|
+
readonly artifactId: string | null;
|
|
34
|
+
/** The event type from DATA_MODEL §4's catalog (`version.published` …). */
|
|
35
|
+
readonly type: string;
|
|
36
|
+
/** Who caused it. Default: an agent, the publisher of versions. */
|
|
37
|
+
readonly actor?: EventActor;
|
|
38
|
+
/** What caused it: a run, a mutation, a submission. */
|
|
39
|
+
readonly causation?: Readonly<Record<string, string>>;
|
|
40
|
+
/** The event's data, JSON. Never a sensitive field's value (D52). */
|
|
41
|
+
readonly payload: Readonly<Record<string, unknown>>;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/** Redactors whose secrets no event may carry (D44, AC-06): the instances of this process. */
|
|
45
|
+
const redactors = new Set<{ redact(text: string): string }>();
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* Makes every event payload pass through `redactor` before it is stored: a secret that server
|
|
49
|
+
* code put into a signal, a host event or a state value never enters the event log. Returns the
|
|
50
|
+
* function that stops it (an instance's stop).
|
|
51
|
+
*/
|
|
52
|
+
export function redactEvents(redactor: { redact(text: string): string }): () => void {
|
|
53
|
+
redactors.add(redactor);
|
|
54
|
+
return () => redactors.delete(redactor);
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/** `value` with every string (keys too) redacted, its structure kept. */
|
|
58
|
+
function redacted(value: unknown): unknown {
|
|
59
|
+
if (redactors.size === 0) return value;
|
|
60
|
+
const text = (input: string): string => {
|
|
61
|
+
let out = input;
|
|
62
|
+
for (const redactor of redactors) out = redactor.redact(out);
|
|
63
|
+
return out;
|
|
64
|
+
};
|
|
65
|
+
const walk = (item: unknown): unknown => {
|
|
66
|
+
if (typeof item === "string") return text(item);
|
|
67
|
+
if (Array.isArray(item)) return item.map(walk);
|
|
68
|
+
if (item !== null && typeof item === "object") {
|
|
69
|
+
return Object.fromEntries(
|
|
70
|
+
Object.entries(item).map(([key, entry]) => [text(key), walk(entry)]),
|
|
71
|
+
);
|
|
72
|
+
}
|
|
73
|
+
return item;
|
|
74
|
+
};
|
|
75
|
+
return walk(value);
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* Appends one event inside the caller's write transaction and returns its cursor (a decimal
|
|
80
|
+
* string, INTERFACES §1). The per-artifact sequence continues from the artifact's last event.
|
|
81
|
+
* Secrets the instance knows are redacted from its payload.
|
|
82
|
+
*/
|
|
83
|
+
export function appendEvent(db: LedgerDb, event: NewEvent): string {
|
|
84
|
+
const seq =
|
|
85
|
+
event.artifactId === null
|
|
86
|
+
? null
|
|
87
|
+
: (db.get<{ next: number }>(
|
|
88
|
+
"SELECT COALESCE(MAX(seq), 0) + 1 AS next FROM event WHERE artifact_id = ?",
|
|
89
|
+
event.artifactId,
|
|
90
|
+
)?.next ?? 1);
|
|
91
|
+
const result = db.run(
|
|
92
|
+
"INSERT INTO event (artifact_id, seq, type, actor_json, causation_json, payload_json, at) VALUES (?, ?, ?, ?, ?, ?, ?)",
|
|
93
|
+
event.artifactId,
|
|
94
|
+
seq,
|
|
95
|
+
event.type,
|
|
96
|
+
JSON.stringify(event.actor ?? { kind: "agent" }),
|
|
97
|
+
event.causation === undefined ? null : JSON.stringify(event.causation),
|
|
98
|
+
JSON.stringify(redacted(event.payload)),
|
|
99
|
+
new Date().toISOString(),
|
|
100
|
+
);
|
|
101
|
+
return String(result.lastInsertRowid);
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/** An `event` row. */
|
|
105
|
+
export interface EventRow {
|
|
106
|
+
readonly cursor: number;
|
|
107
|
+
readonly artifact_id: string | null;
|
|
108
|
+
readonly seq: number | null;
|
|
109
|
+
readonly type: string;
|
|
110
|
+
readonly actor_json: string;
|
|
111
|
+
readonly causation_json: string | null;
|
|
112
|
+
readonly payload_json: string;
|
|
113
|
+
readonly at: string;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/** An event row as the wire carries it. */
|
|
117
|
+
export function eventRecord(row: EventRow): EventRecord {
|
|
118
|
+
return {
|
|
119
|
+
cursor: String(row.cursor) as Cursor,
|
|
120
|
+
artifactId: row.artifact_id,
|
|
121
|
+
seq: row.seq,
|
|
122
|
+
type: row.type,
|
|
123
|
+
at: row.at,
|
|
124
|
+
actor: JSON.parse(row.actor_json) as Actor,
|
|
125
|
+
...(row.causation_json !== null
|
|
126
|
+
? { causation: JSON.parse(row.causation_json) as Record<string, string> }
|
|
127
|
+
: {}),
|
|
128
|
+
payload: JSON.parse(row.payload_json) as Record<string, unknown>,
|
|
129
|
+
};
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/** The newest cursor in the home, or 0 before the first event. */
|
|
133
|
+
export function latestCursor(db: LedgerDb): number {
|
|
134
|
+
return db.get<{ cursor: number }>("SELECT COALESCE(MAX(cursor), 0) AS cursor FROM event")
|
|
135
|
+
?.cursor as number;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/** The type of the event compaction leaves behind (DATA_MODEL §4). */
|
|
139
|
+
export const COMPACTED = "artifact.compacted";
|
|
140
|
+
|
|
141
|
+
/** The SQL condition and parameters of a filter, applied before any row is parsed. */
|
|
142
|
+
function filterSql(filter: EventFilter | undefined): {
|
|
143
|
+
where: string;
|
|
144
|
+
params: (string | number)[];
|
|
145
|
+
} {
|
|
146
|
+
const clauses: string[] = [];
|
|
147
|
+
const params: (string | number)[] = [];
|
|
148
|
+
if (filter?.artifacts) {
|
|
149
|
+
if (filter.artifacts.length === 0) return { where: "0", params: [] };
|
|
150
|
+
clauses.push(`artifact_id IN (${filter.artifacts.map(() => "?").join(", ")})`);
|
|
151
|
+
params.push(...filter.artifacts);
|
|
152
|
+
}
|
|
153
|
+
if (filter?.types) {
|
|
154
|
+
const alternatives = [`type = '${COMPACTED}'`];
|
|
155
|
+
for (const pattern of filter.types) {
|
|
156
|
+
if (pattern.endsWith(".*")) {
|
|
157
|
+
const prefix = pattern.slice(0, -1);
|
|
158
|
+
alternatives.push("substr(type, 1, ?) = ?");
|
|
159
|
+
params.push(prefix.length, prefix);
|
|
160
|
+
} else {
|
|
161
|
+
alternatives.push("type = ?");
|
|
162
|
+
params.push(pattern);
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
clauses.push(`(${alternatives.join(" OR ")})`);
|
|
166
|
+
}
|
|
167
|
+
return { where: clauses.length === 0 ? "1" : clauses.join(" AND "), params };
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
/**
|
|
171
|
+
* The compaction summary whose range holds `after` for an artifact the filter covers: the reader
|
|
172
|
+
* already had events of that range (`from <= after`), and the ones after its cursor are gone
|
|
173
|
+
* (`after < through`, the summary's own cursor). A reader before the range receives the summary in
|
|
174
|
+
* its place, in order, and continues after it (DATA_MODEL §4).
|
|
175
|
+
*/
|
|
176
|
+
export function compactionCovering(
|
|
177
|
+
db: LedgerDb,
|
|
178
|
+
filter: EventFilter | undefined,
|
|
179
|
+
after: number,
|
|
180
|
+
): EventRow | undefined {
|
|
181
|
+
const { where, params } = filterSql(filter?.artifacts ? { artifacts: filter.artifacts } : {});
|
|
182
|
+
return db.get<EventRow>(
|
|
183
|
+
`SELECT * FROM event WHERE type = '${COMPACTED}' AND ${where} AND json_extract(payload_json, '$.from') <= ? AND cursor > ? ORDER BY cursor LIMIT 1`,
|
|
184
|
+
...params,
|
|
185
|
+
after,
|
|
186
|
+
after,
|
|
187
|
+
);
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/** Refuses a read whose cursor falls inside a compacted range (`MOSTRA_HOST_CURSOR_COMPACTED`). */
|
|
191
|
+
export function checkCompaction(
|
|
192
|
+
db: LedgerDb,
|
|
193
|
+
filter: EventFilter | undefined,
|
|
194
|
+
after: number,
|
|
195
|
+
): void {
|
|
196
|
+
const hit = compactionCovering(db, filter, after);
|
|
197
|
+
if (hit) {
|
|
198
|
+
const from = (JSON.parse(hit.payload_json) as CompactionSummary).from;
|
|
199
|
+
throw new RpcError(
|
|
200
|
+
createDiagnostic("MOSTRA_HOST_CURSOR_COMPACTED", {
|
|
201
|
+
message: `Events after cursor ${after} were compacted into a summary at cursor ${hit.cursor}; read again after cursor ${from - 1} to receive it (events of other artifacts in between may repeat).`,
|
|
202
|
+
}),
|
|
203
|
+
);
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/** The most a page of events carries, as JSON: well inside every framing limit (D83). */
|
|
208
|
+
export const READ_MAX_BYTES: number = 8 * 1024 * 1024;
|
|
209
|
+
|
|
210
|
+
/** Options for {@link readEvents}. */
|
|
211
|
+
export interface ReadOptions {
|
|
212
|
+
readonly filter?: EventFilter | undefined;
|
|
213
|
+
/** Events after this cursor. */
|
|
214
|
+
readonly after: number;
|
|
215
|
+
/** At most this many events. */
|
|
216
|
+
readonly limit: number;
|
|
217
|
+
/** At most about this many bytes of events; one event always fits. Default {@link READ_MAX_BYTES}. */
|
|
218
|
+
readonly maxBytes?: number;
|
|
219
|
+
/**
|
|
220
|
+
* Read on through a compacted range that holds `after` instead of refusing it: the summary
|
|
221
|
+
* arrives in cursor order among other artifacts' events, so nothing between is skipped, and the
|
|
222
|
+
* page that carries it says so (`compacted`).
|
|
223
|
+
*/
|
|
224
|
+
readonly acceptCompacted?: boolean;
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
/**
|
|
228
|
+
* Reads matching events after a cursor, in order, inside the caller's read transaction. The
|
|
229
|
+
* returned cursor is where the next read continues: the last event returned when the page is full
|
|
230
|
+
* (by count or by size), else the newest cursor examined, so non-matching events are never
|
|
231
|
+
* examined twice and an event left out is never skipped.
|
|
232
|
+
*/
|
|
233
|
+
export function readEvents(
|
|
234
|
+
db: LedgerDb,
|
|
235
|
+
options: ReadOptions,
|
|
236
|
+
): { readonly events: EventRecord[]; readonly cursor: string; readonly compacted?: Diagnostic } {
|
|
237
|
+
let covering: EventRow | undefined;
|
|
238
|
+
if (options.acceptCompacted) covering = compactionCovering(db, options.filter, options.after);
|
|
239
|
+
else checkCompaction(db, options.filter, options.after);
|
|
240
|
+
const upTo = latestCursor(db);
|
|
241
|
+
const { where, params } = filterSql(options.filter);
|
|
242
|
+
const rows = db.all<EventRow>(
|
|
243
|
+
`SELECT * FROM event WHERE cursor > ? AND cursor <= ? AND ${where} ORDER BY cursor LIMIT ?`,
|
|
244
|
+
options.after,
|
|
245
|
+
upTo,
|
|
246
|
+
...params,
|
|
247
|
+
options.limit,
|
|
248
|
+
);
|
|
249
|
+
const maxBytes = options.maxBytes ?? READ_MAX_BYTES;
|
|
250
|
+
const events: EventRecord[] = [];
|
|
251
|
+
let bytes = 0;
|
|
252
|
+
let full = rows.length === options.limit;
|
|
253
|
+
for (const row of rows) {
|
|
254
|
+
const size =
|
|
255
|
+
row.payload_json.length + row.actor_json.length + (row.causation_json?.length ?? 0) + 256;
|
|
256
|
+
if (events.length > 0 && bytes + size > maxBytes) {
|
|
257
|
+
full = true;
|
|
258
|
+
break;
|
|
259
|
+
}
|
|
260
|
+
bytes += size;
|
|
261
|
+
events.push(eventRecord(row));
|
|
262
|
+
}
|
|
263
|
+
const last = events.at(-1)?.cursor;
|
|
264
|
+
const cursor = full && last !== undefined ? Number(last) : Math.max(upTo, options.after);
|
|
265
|
+
// The page that carries the summary says that events after `after` were lost.
|
|
266
|
+
const compacted =
|
|
267
|
+
covering !== undefined && events.some((event) => Number(event.cursor) === covering.cursor)
|
|
268
|
+
? createDiagnostic("MOSTRA_HOST_CURSOR_COMPACTED", {
|
|
269
|
+
message: `Events after cursor ${options.after} were compacted; the summary at cursor ${covering.cursor} stands in for them.`,
|
|
270
|
+
})
|
|
271
|
+
: undefined;
|
|
272
|
+
return { events, cursor: String(cursor), ...(compacted ? { compacted } : {}) };
|
|
273
|
+
}
|
|
274
|
+
|
|
275
|
+
/** What compaction left behind: the `artifact.compacted` event's payload (DATA_MODEL §4). */
|
|
276
|
+
export interface CompactionSummary {
|
|
277
|
+
/** The first cursor the summary covers. */
|
|
278
|
+
readonly from: number;
|
|
279
|
+
/** The last cursor it covers, which is its own: the artifact's events in between were replaced. */
|
|
280
|
+
readonly through: number;
|
|
281
|
+
/** How many events it replaced. */
|
|
282
|
+
readonly removed: number;
|
|
283
|
+
/** How many of each type. */
|
|
284
|
+
readonly types: Readonly<Record<string, number>>;
|
|
285
|
+
/** The latest version published within the range. */
|
|
286
|
+
readonly latestVersion?: {
|
|
287
|
+
readonly versionId: unknown;
|
|
288
|
+
readonly number: unknown;
|
|
289
|
+
readonly cursor: number;
|
|
290
|
+
};
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
/**
|
|
294
|
+
* Compacts an artifact's events before `before` (`mostra gc --compact-events`, D47): they are
|
|
295
|
+
* replaced, in this transaction, by one `artifact.compacted` event at the last replaced cursor and
|
|
296
|
+
* sequence, whose payload summarizes them (an earlier summary in the range folds in). Cursors and
|
|
297
|
+
* per-artifact sequences therefore never move back, and a reader who receives the summary
|
|
298
|
+
* continues after it. Returns the summary, or `undefined` when there was nothing to replace.
|
|
299
|
+
*/
|
|
300
|
+
export function compactEvents(
|
|
301
|
+
db: LedgerDb,
|
|
302
|
+
artifactId: string,
|
|
303
|
+
before: number,
|
|
304
|
+
): CompactionSummary | undefined {
|
|
305
|
+
const rows = db.all<EventRow>(
|
|
306
|
+
"SELECT * FROM event WHERE artifact_id = ? AND cursor < ? ORDER BY cursor",
|
|
307
|
+
artifactId,
|
|
308
|
+
before,
|
|
309
|
+
);
|
|
310
|
+
const first = rows[0];
|
|
311
|
+
const last = rows.at(-1);
|
|
312
|
+
if (!first || !last) return undefined;
|
|
313
|
+
if (rows.length === 1 && first.type === COMPACTED) return undefined;
|
|
314
|
+
const types: Record<string, number> = {};
|
|
315
|
+
let removed = 0;
|
|
316
|
+
let from = first.cursor;
|
|
317
|
+
let latestVersion: CompactionSummary["latestVersion"];
|
|
318
|
+
for (const row of rows) {
|
|
319
|
+
if (row.type === COMPACTED) {
|
|
320
|
+
// An earlier summary folds into this one, with everything it covered.
|
|
321
|
+
const earlier = JSON.parse(row.payload_json) as CompactionSummary;
|
|
322
|
+
from = Math.min(from, earlier.from);
|
|
323
|
+
removed += earlier.removed;
|
|
324
|
+
for (const [type, count] of Object.entries(earlier.types))
|
|
325
|
+
types[type] = (types[type] ?? 0) + count;
|
|
326
|
+
if (earlier.latestVersion) latestVersion = earlier.latestVersion;
|
|
327
|
+
continue;
|
|
328
|
+
}
|
|
329
|
+
removed += 1;
|
|
330
|
+
types[row.type] = (types[row.type] ?? 0) + 1;
|
|
331
|
+
if (row.type === "version.published") {
|
|
332
|
+
const payload = JSON.parse(row.payload_json) as { versionId?: unknown; number?: unknown };
|
|
333
|
+
latestVersion = { versionId: payload.versionId, number: payload.number, cursor: row.cursor };
|
|
334
|
+
}
|
|
335
|
+
}
|
|
336
|
+
const summary: CompactionSummary = {
|
|
337
|
+
from,
|
|
338
|
+
through: last.cursor,
|
|
339
|
+
removed,
|
|
340
|
+
types,
|
|
341
|
+
...(latestVersion ? { latestVersion } : {}),
|
|
342
|
+
};
|
|
343
|
+
db.run("DELETE FROM event WHERE artifact_id = ? AND cursor < ?", artifactId, before);
|
|
344
|
+
db.run(
|
|
345
|
+
"INSERT INTO event (cursor, artifact_id, seq, type, actor_json, causation_json, payload_json, at) VALUES (?, ?, ?, ?, ?, NULL, ?, ?)",
|
|
346
|
+
last.cursor,
|
|
347
|
+
artifactId,
|
|
348
|
+
last.seq,
|
|
349
|
+
COMPACTED,
|
|
350
|
+
JSON.stringify({ kind: "mostra" }),
|
|
351
|
+
JSON.stringify(summary),
|
|
352
|
+
new Date().toISOString(),
|
|
353
|
+
);
|
|
354
|
+
return summary;
|
|
355
|
+
}
|