@mostra/runtime 0.8.0 → 0.10.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 (65) hide show
  1. package/dist/bin.js +2879 -8
  2. package/dist/bin.js.map +1 -1
  3. package/dist/builder/child/main.js +2 -2
  4. package/dist/{child-Chiavhdx.js → child-BmNZ4a70.js} +2 -2
  5. package/dist/{child-Chiavhdx.js.map → child-BmNZ4a70.js.map} +1 -1
  6. package/dist/deps/child/install.js +1 -1
  7. package/dist/{directories-mJ1qlVht.js → directories-BLJjeSPD.js} +5 -5
  8. package/dist/directories-BLJjeSPD.js.map +1 -0
  9. package/dist/{files-FygSJIzK.js → files-DGeWuE4I.js} +2 -2
  10. package/dist/{files-FygSJIzK.js.map → files-DGeWuE4I.js.map} +1 -1
  11. package/dist/index.d.ts +2 -0
  12. package/dist/index.d.ts.map +1 -1
  13. package/dist/index.js +2 -2
  14. package/dist/{instance-BRfg27Rg.js → instance-FExcyENK.js} +3346 -395
  15. package/dist/instance-FExcyENK.js.map +1 -0
  16. package/package.json +7 -5
  17. package/src/actions/index.ts +163 -10
  18. package/src/bin.ts +78 -1
  19. package/src/gateway/actions.ts +20 -4
  20. package/src/gateway/browser.ts +118 -95
  21. package/src/gateway/capabilities.ts +15 -6
  22. package/src/gateway/index.ts +112 -15
  23. package/src/gateway/routes.ts +15 -7
  24. package/src/gc/index.ts +14 -0
  25. package/src/instance/index.ts +41 -2
  26. package/src/interaction/ephemeral.ts +32 -23
  27. package/src/interaction/events.ts +21 -1
  28. package/src/interaction/imports.ts +317 -0
  29. package/src/interaction/index.ts +172 -19
  30. package/src/interaction/outbox.ts +9 -0
  31. package/src/interaction/results.ts +22 -1
  32. package/src/interaction/runs.ts +52 -2
  33. package/src/interaction/submissions.ts +17 -1
  34. package/src/interaction/tally.ts +129 -0
  35. package/src/ledger/index.ts +104 -9
  36. package/src/ledger/migrations.ts +183 -0
  37. package/src/ledger/types.ts +8 -0
  38. package/src/link/binding.ts +289 -0
  39. package/src/link/hosted.ts +65 -0
  40. package/src/link/http.ts +136 -0
  41. package/src/link/index.ts +8 -0
  42. package/src/link/manager.ts +1385 -0
  43. package/src/link/relay.ts +512 -0
  44. package/src/live/index.ts +112 -2
  45. package/src/platform/filesystems.ts +78 -0
  46. package/src/platform/index.ts +1 -0
  47. package/src/protocol-server/index.ts +18 -1
  48. package/src/protocol-server/server.ts +38 -7
  49. package/src/protocol-server/websocket.ts +161 -0
  50. package/src/publish/bundle.ts +398 -0
  51. package/src/publish/manifest.ts +9 -0
  52. package/src/publish/methods.ts +12 -1
  53. package/src/publish/publisher.ts +127 -0
  54. package/src/registry/index.ts +35 -14
  55. package/src/server/api.ts +439 -0
  56. package/src/server/auth.ts +613 -0
  57. package/src/server/config.ts +221 -0
  58. package/src/server/data.ts +369 -0
  59. package/src/server/directory.ts +141 -0
  60. package/src/server/hosted.ts +822 -0
  61. package/src/server/index.ts +368 -0
  62. package/src/server/relay.ts +1163 -0
  63. package/src/share/index.ts +110 -6
  64. package/dist/directories-mJ1qlVht.js.map +0 -1
  65. package/dist/instance-BRfg27Rg.js.map +0 -1
@@ -80,6 +80,7 @@ import {
80
80
  type Interaction,
81
81
  redactEvents,
82
82
  } from "../interaction/index.ts";
83
+ import { createLink, forwardHosted, hostedState, type Link } from "../link/index.ts";
83
84
  import { createLive, type LatestLive, liveMethods } from "../live/index.ts";
84
85
  import type { Environment, Log } from "../log.ts";
85
86
  import { helperPath, type LaunchPipe, realPath } from "../platform/index.ts";
@@ -563,6 +564,9 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
563
564
  : {}),
564
565
  });
565
566
  const actions = createActions({
567
+ // Server code's `state` of a hosted artifact acts on its hosted home (D165 item 1); the link
568
+ // is made below, and asked only once runs start.
569
+ hostedState: (artifactId) => hostedState(link, artifactId),
566
570
  interaction,
567
571
  pool,
568
572
  bus,
@@ -597,6 +601,10 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
597
601
  return versionId ? { versionId, sources: sourcesOf(versionId) } : undefined;
598
602
  };
599
603
  const live = createLive({
604
+ // A hosted artifact's live sources: produced here while its hosted pages want them, their
605
+ // values kept on its hosted home (D165 items 1 and 4). The link is made below.
606
+ extraInterest: () => link.liveInterest(),
607
+ forward: (artifactId, versionId, produced) => link.forwardLive(artifactId, versionId, produced),
600
608
  ledger: home.ledger,
601
609
  log,
602
610
  bus,
@@ -738,6 +746,24 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
738
746
  }
739
747
  },
740
748
  });
749
+ // The owner's side of remote servers (WP-29, D165): sign-in, the bindings, hosted deliveries
750
+ // imported into this home's outbox, the sync cursor, and version pushes.
751
+ const link: Link = createLink({
752
+ home: home.path,
753
+ ledger: home.ledger,
754
+ log,
755
+ env: environment,
756
+ runtimeVersion: runtimeVersion(),
757
+ protect: (value) => home.redactor.protect(value),
758
+ importSubmission: (envelope, source) => interaction.importSubmission(envelope, source),
759
+ versionDir: (versionId) => registry.store.versionDir(versionId),
760
+ actions,
761
+ liveChanged: () => live.reconcile(),
762
+ now: () => Date.now() + clockOffset,
763
+ });
764
+ const stopPushingPublishes = interaction.onPublished((artifactId, versionId) =>
765
+ link.published(artifactId, versionId),
766
+ );
741
767
  // Shares (WP-13, D158): tunnels to the gateway's faces, each with a link of its own.
742
768
  const shares: Shares = createShares({
743
769
  ledger: home.ledger,
@@ -751,6 +777,8 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
751
777
  toolEnvironment: artifactEnvironment(environment),
752
778
  cacheDir: shareCacheDir(home.path),
753
779
  now: () => Date.now() + clockOffset,
780
+ // Shares to a remote server go through the owner's link (D165, INTERFACES §18.2).
781
+ remote: link.shares(),
754
782
  ...(environment["MOSTRA_TEST_SHARE_PROBE_MS"] !== undefined
755
783
  ? { probeMs: Number(environment["MOSTRA_TEST_SHARE_PROBE_MS"]) }
756
784
  : {}),
@@ -850,7 +878,9 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
850
878
  ...dev.methods(),
851
879
  ...gateway.methods(),
852
880
  ...shares.methods(),
853
- ...interaction.methods(),
881
+ ...link.methods(),
882
+ // A hosted artifact's state and live values act on its hosted home (D165 item 1).
883
+ ...forwardHosted(link, (ref) => registry.get(canonicalRef(ref)).id, interaction.methods()),
854
884
  ...secretMethods(secrets, (ref) => registry.get(canonicalRef(ref)).id),
855
885
  ...gcMethods(
856
886
  createGc({
@@ -868,7 +898,11 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
868
898
  faults,
869
899
  }),
870
900
  ),
871
- ...liveMethods(live, (ref) => registry.get(canonicalRef(ref)).id),
901
+ ...forwardHosted(
902
+ link,
903
+ (ref) => registry.get(canonicalRef(ref)).id,
904
+ liveMethods(live, (ref) => registry.get(canonicalRef(ref)).id),
905
+ ),
872
906
  ...sessionMethods({
873
907
  describe: () => info,
874
908
  startedAt: home.startedAt,
@@ -888,6 +922,7 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
888
922
  }
889
923
  : undefined,
890
924
  shares: () => shares.active(),
925
+ links: () => link.status(),
891
926
  deliveries: () => interaction.deliveries(),
892
927
  workers: () => pool.status(),
893
928
  idleExitAt: () => idle?.exitAt(),
@@ -917,6 +952,8 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
917
952
  log.info("instance.stopping", { reason, exitCode, ...(diagnostic ? { diagnostic } : {}) });
918
953
  idle?.stop();
919
954
  stopWatchingPublishes();
955
+ stopPushingPublishes();
956
+ await link.stop();
920
957
  live.stop();
921
958
  interaction.stop();
922
959
  // Before any child stops: on Windows the pipe's helper is a child, and it hands clients
@@ -973,6 +1010,8 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
973
1010
  interaction.start();
974
1011
  // Producers that `always` run, and those hosts subscribe to, start now (LL-04).
975
1012
  live.start();
1013
+ // Every server this home is signed in to is dialled again (D165 item 2).
1014
+ link.start();
976
1015
  // Tailnet and Funnel shares come back; what can't continue ends, with its reason (D158).
977
1016
  void shares.recover().catch((error: unknown) => log.error("share.recover_failed", { error }));
978
1017
  home.publish(options.mode, server.socketPath ?? home.socketPath);
@@ -14,15 +14,22 @@ export const INTEREST_LEASE_MS: number = 60_000;
14
14
  /** The most messages a polling view keeps between polls; older ones are dropped. */
15
15
  const POLL_QUEUE_MAX = 1000;
16
16
 
17
+ /** A polling view's messages collected between its polls. */
18
+ interface PollQueue {
19
+ readonly messages: EphemeralMessage[];
20
+ until: number;
21
+ /** The polls waiting now; each is woken by the next message. */
22
+ readonly wakes: Set<() => void>;
23
+ }
24
+
17
25
  /** What a view listens to. */
18
26
  interface ViewInterest {
19
27
  readonly artifactId: string;
20
28
  readonly runs: Map<string, number>;
21
29
  readonly live: Map<string, { until: number; window?: number }>;
22
30
  readonly listeners: Set<(message: EphemeralMessage) => void>;
23
- queue?: EphemeralMessage[];
24
- queueUntil?: number;
25
- wake?: () => void;
31
+ /** Its frame's poll queue, once the frame polled. */
32
+ poll?: PollQueue;
26
33
  }
27
34
 
28
35
  type RunMessage = Extract<EphemeralMessage, { kind: "run" }>;
@@ -123,9 +130,12 @@ export interface EphemeralBus {
123
130
  viewId: string,
124
131
  listener: (message: EphemeralMessage) => void,
125
132
  ): () => void;
126
- /** Takes what the view collected since its last poll, starting its queue on the first. */
133
+ /**
134
+ * Takes what the view's frame collected since its last poll, starting its queue on the first.
135
+ * Only the frame polls for these: the shell's poll of the same view never takes them (#119).
136
+ */
127
137
  drain(artifactId: string, viewId: string): EphemeralMessage[];
128
- /** Resolves when the polling view has something, or after `ms`. */
138
+ /** Resolves when the polling view has something, or after `ms`; several polls may wait. */
129
139
  wait(artifactId: string, viewId: string, ms: number, signal?: AbortSignal): Promise<void>;
130
140
  /** The live sources views read now. */
131
141
  liveInterest(): LiveInterest[];
@@ -181,12 +191,12 @@ export function createEphemeralBus(
181
191
 
182
192
  const deliver = (view: ViewInterest, message: EphemeralMessage): void => {
183
193
  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
- }
194
+ const poll = view.poll;
195
+ if (!poll || poll.until <= now()) return;
196
+ coalesceInto(view, poll.messages, message);
197
+ if (poll.messages.length > POLL_QUEUE_MAX)
198
+ poll.messages.splice(0, poll.messages.length - POLL_QUEUE_MAX);
199
+ for (const wake of [...poll.wakes]) wake();
190
200
  };
191
201
 
192
202
  // Expired leases end; views with nothing left are forgotten.
@@ -196,15 +206,12 @@ export function createEphemeralBus(
196
206
  for (const [viewId, view] of views) {
197
207
  for (const [runId, until] of view.runs) if (until <= at) view.runs.delete(runId);
198
208
  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
- }
209
+ if (view.poll && view.poll.until <= at && view.poll.wakes.size === 0) delete view.poll;
203
210
  if (
204
211
  view.runs.size === 0 &&
205
212
  view.live.size === 0 &&
206
213
  view.listeners.size === 0 &&
207
- !view.queue
214
+ !view.poll
208
215
  ) {
209
216
  views.delete(viewId);
210
217
  }
@@ -258,24 +265,26 @@ export function createEphemeralBus(
258
265
  },
259
266
  drain(artifactId, viewId) {
260
267
  const view = viewOf(artifactId, viewId);
261
- const taken = view.queue ?? [];
262
- view.queue = [];
263
- view.queueUntil = now() + lease;
268
+ const taken = view.poll ? view.poll.messages.splice(0) : [];
269
+ if (view.poll) view.poll.until = now() + lease;
270
+ else view.poll = { messages: [], until: now() + lease, wakes: new Set() };
264
271
  return taken;
265
272
  },
266
273
  wait(artifactId, viewId, ms, signal) {
267
274
  const view = viewOf(artifactId, viewId);
268
- if (view.queue && view.queue.length > 0) return Promise.resolve();
275
+ view.poll ??= { messages: [], until: now() + lease, wakes: new Set() };
276
+ if (view.poll.messages.length > 0) return Promise.resolve();
277
+ const waiting = view.poll;
269
278
  return new Promise((resolve) => {
270
279
  const done = (): void => {
271
280
  clearTimeout(timer);
272
281
  signal?.removeEventListener("abort", done);
273
- if (view.wake === done) delete view.wake;
282
+ waiting.wakes.delete(done);
274
283
  resolve();
275
284
  };
276
285
  const timer = setTimeout(done, ms);
277
286
  signal?.addEventListener("abort", done, { once: true });
278
- view.wake = done;
287
+ waiting.wakes.add(done);
279
288
  });
280
289
  },
281
290
  liveInterest: currentInterest,
@@ -289,7 +298,7 @@ export function createEphemeralBus(
289
298
  const at = now();
290
299
  let count = 0;
291
300
  for (const view of views.values()) {
292
- if (view.listeners.size > 0 || (view.queueUntil ?? 0) > at) count += 1;
301
+ if (view.listeners.size > 0 || (view.poll?.until ?? 0) > at) count += 1;
293
302
  }
294
303
  return count;
295
304
  },
@@ -19,6 +19,7 @@ import {
19
19
  createDiagnostic,
20
20
  type Diagnostic,
21
21
  type EventFilter,
22
+ type EventOrigin,
22
23
  type EventRecord,
23
24
  RpcError,
24
25
  } from "@mostra/protocol";
@@ -39,6 +40,8 @@ export interface NewEvent {
39
40
  readonly causation?: Readonly<Record<string, string>>;
40
41
  /** The event's data, JSON. Never a sensitive field's value (D52). */
41
42
  readonly payload: Readonly<Record<string, unknown>>;
43
+ /** For an event an owner instance copies from its hosted home: where it came from (§18.2). */
44
+ readonly origin?: EventOrigin;
42
45
  }
43
46
 
44
47
  /** Redactors whose secrets no event may carry (D44, AC-06): the instances of this process. */
@@ -89,7 +92,11 @@ export function appendEvent(db: LedgerDb, event: NewEvent): string {
89
92
  event.artifactId,
90
93
  )?.next ?? 1);
91
94
  const result = db.run(
92
- "INSERT INTO event (artifact_id, seq, type, actor_json, causation_json, payload_json, at) VALUES (?, ?, ?, ?, ?, ?, ?)",
95
+ // `origin_json` (migration 13) is named only for a followed event, so a ledger still at an older
96
+ // schema (a migration's own tests) appends as before.
97
+ event.origin === undefined
98
+ ? "INSERT INTO event (artifact_id, seq, type, actor_json, causation_json, payload_json, at) VALUES (?, ?, ?, ?, ?, ?, ?)"
99
+ : "INSERT INTO event (artifact_id, seq, type, actor_json, causation_json, payload_json, at, origin_json) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
93
100
  event.artifactId,
94
101
  seq,
95
102
  event.type,
@@ -97,6 +104,7 @@ export function appendEvent(db: LedgerDb, event: NewEvent): string {
97
104
  event.causation === undefined ? null : JSON.stringify(event.causation),
98
105
  JSON.stringify(redacted(event.payload)),
99
106
  new Date().toISOString(),
107
+ ...(event.origin === undefined ? [] : [originJson(event.origin)]),
100
108
  );
101
109
  return String(result.lastInsertRowid);
102
110
  }
@@ -111,6 +119,17 @@ export interface EventRow {
111
119
  readonly causation_json: string | null;
112
120
  readonly payload_json: string;
113
121
  readonly at: string;
122
+ readonly origin_json?: string | null;
123
+ }
124
+
125
+ /** An origin's stored form: its keys in one order, so one origin is one text (the unique index). */
126
+ export function originJson(origin: EventOrigin): string {
127
+ return JSON.stringify({
128
+ server: origin.server,
129
+ home: origin.home,
130
+ incarnation: origin.incarnation,
131
+ cursor: origin.cursor,
132
+ });
114
133
  }
115
134
 
116
135
  /** An event row as the wire carries it. */
@@ -126,6 +145,7 @@ export function eventRecord(row: EventRow): EventRecord {
126
145
  ? { causation: JSON.parse(row.causation_json) as Record<string, string> }
127
146
  : {}),
128
147
  payload: JSON.parse(row.payload_json) as Record<string, unknown>,
148
+ ...(row.origin_json ? { origin: JSON.parse(row.origin_json) as EventOrigin } : {}),
129
149
  };
130
150
  }
131
151
 
@@ -0,0 +1,317 @@
1
+ /**
2
+ * The owner instance's copies of its hosted homes' records (D165 item 1, DATA_MODEL §7.3): the
3
+ * submissions a hosted home delivers to it, stored with their hosted IDs, digest and snapshot and
4
+ * enqueued to the owner's own hosts in the same transaction, so remote submissions reach local hosts
5
+ * through the local outbox (RM-02, H-04); and the events the sync cursor follows, each appended
6
+ * once, with where it came from.
7
+ */
8
+ import { createHash } from "node:crypto";
9
+ import {
10
+ type EventOrigin,
11
+ type EventRecord,
12
+ type SubmissionEnvelope,
13
+ type SubmissionsDeliverResult,
14
+ ViewerId,
15
+ } from "@mostra/protocol";
16
+ import type { LedgerDb } from "../ledger/index.ts";
17
+ import { appendEvent, originJson } from "./events.ts";
18
+ import { documentFor } from "./fields.ts";
19
+ import type { Snapshot } from "./submissions.ts";
20
+
21
+ /** The built-in adapter's owner name, as `submit` uses it (D105). */
22
+ import { BUILT_IN_OWNER } from "./submissions.ts";
23
+
24
+ const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
25
+
26
+ /**
27
+ * A local delivery's ID for an imported submission and one of the owner's hosts: `dlv_` and 26
28
+ * Crockford base32 characters of SHA-256(submission ID ‖ 0x00 ‖ host owner), its first two bits
29
+ * cleared so it reads as a ULID. A re-import (the owner's home restored) repeats it, so a host
30
+ * that dedupes by delivery ID sees one delivery (DATA_MODEL §7.3, D105's identity).
31
+ */
32
+ export function importedDeliveryId(submissionId: string, owner: string): string {
33
+ const digest = createHash("sha256")
34
+ .update(
35
+ Buffer.concat([
36
+ Buffer.from(submissionId, "utf8"),
37
+ Buffer.from([0]),
38
+ Buffer.from(owner, "utf8"),
39
+ ]),
40
+ )
41
+ .digest();
42
+ digest[0] = (digest[0] as number) & 0x3f;
43
+ let out = "";
44
+ let buffer = 0;
45
+ let bits = 0;
46
+ for (const byte of digest) {
47
+ buffer = (buffer << 8) | byte;
48
+ bits += 8;
49
+ while (bits >= 5 && out.length < 26) {
50
+ bits -= 5;
51
+ out += CROCKFORD.charAt((buffer >> bits) & 31);
52
+ }
53
+ if (out.length >= 26) break;
54
+ }
55
+ return `dlv_${out}`;
56
+ }
57
+
58
+ /** Where an imported record came from, without its own cursor. */
59
+ export interface ImportSource {
60
+ /** The server's API origin. */
61
+ readonly server: string;
62
+ /** A short, stable key of the server: imported viewers' references are prefixed by it. */
63
+ readonly serverKey: string;
64
+ /** The hosted home and its incarnation now. */
65
+ readonly home: string;
66
+ readonly incarnation: string;
67
+ }
68
+
69
+ /** What {@link importSubmission} needs. */
70
+ export interface SubmissionImport {
71
+ readonly envelope: SubmissionEnvelope;
72
+ readonly source: ImportSource;
73
+ /** The owner's own hosts for submissions, or none (the built-in adapter accepts). */
74
+ readonly owners: readonly string[];
75
+ /** Whether this instance owns the artifact on that server (its `hosted_artifact` row). */
76
+ readonly owned: (db: LedgerDb, artifactId: string) => boolean;
77
+ }
78
+
79
+ /**
80
+ * Stores a delivered hosted submission and its local deliveries in the caller's transaction, and
81
+ * answers the hosted home as a host does (D105): `accepted` once it is durable here, a repeat of
82
+ * one already held too; a submission it can never hold is refused for good.
83
+ */
84
+ export function importSubmission(db: LedgerDb, input: SubmissionImport): SubmissionsDeliverResult {
85
+ const { envelope, source } = input;
86
+ const refuse = (reason: string): SubmissionsDeliverResult => ({
87
+ accepted: false,
88
+ reason,
89
+ retry: false,
90
+ });
91
+ if (db.get("SELECT 1 FROM submission WHERE id = ?", envelope.submissionId))
92
+ return { accepted: true };
93
+ if (envelope.snapshot === undefined) return refuse("invalid: the delivery carries no snapshot");
94
+ const digest = createHash("sha256").update(envelope.snapshot, "utf8").digest("hex");
95
+ if (digest !== envelope.results.submission.digest) {
96
+ return refuse("invalid: the snapshot doesn't match the submission's digest");
97
+ }
98
+ let snapshot: Snapshot;
99
+ try {
100
+ snapshot = JSON.parse(envelope.snapshot) as Snapshot;
101
+ } catch {
102
+ return refuse("invalid: the snapshot isn't JSON");
103
+ }
104
+ if (
105
+ snapshot.submissionId !== envelope.submissionId ||
106
+ snapshot.artifactId !== envelope.artifactId ||
107
+ typeof snapshot.versionId !== "string" ||
108
+ typeof snapshot.viewId !== "string"
109
+ ) {
110
+ return refuse("invalid: the snapshot names another submission");
111
+ }
112
+ if (!input.owned(db, snapshot.artifactId)) {
113
+ // Never sent to an instance that doesn't own the artifact (D165 item 1b); refused for good.
114
+ return refuse("undeliverable: this instance doesn't own the artifact");
115
+ }
116
+ if (
117
+ !db.get(
118
+ "SELECT 1 FROM version WHERE id = ? AND artifact_id = ?",
119
+ snapshot.versionId,
120
+ snapshot.artifactId,
121
+ )
122
+ ) {
123
+ return refuse("undeliverable: this instance doesn't hold the submission's version");
124
+ }
125
+
126
+ // The viewer, as a row of its kind keyed by the server (DATA_MODEL §7.3).
127
+ const hostedViewer = snapshot.viewer;
128
+ const kind = hostedViewer.kind === "local" ? "token" : hostedViewer.kind;
129
+ const ref = `${source.serverKey}:${hostedViewer.ref ?? hostedViewer.id}`;
130
+ let viewerId = db.get<{ id: string }>(
131
+ "SELECT id FROM viewer WHERE kind = ? AND external_ref = ?",
132
+ kind,
133
+ ref,
134
+ )?.id;
135
+ if (viewerId === undefined) {
136
+ viewerId = db.get("SELECT 1 FROM viewer WHERE id = ?", hostedViewer.id)
137
+ ? ViewerId.create()
138
+ : hostedViewer.id;
139
+ db.run(
140
+ "INSERT INTO viewer (id, kind, external_ref, name, created_at) VALUES (?, ?, ?, ?, ?)",
141
+ viewerId,
142
+ kind,
143
+ ref,
144
+ hostedViewer.name ?? null,
145
+ snapshot.at,
146
+ );
147
+ }
148
+ // The view it named, under its hosted ID, so the submission names exactly what its tab showed.
149
+ const view = db.get<{ artifact_id: string }>(
150
+ "SELECT artifact_id FROM view WHERE id = ?",
151
+ snapshot.viewId,
152
+ );
153
+ if (view && view.artifact_id !== snapshot.artifactId)
154
+ return refuse("invalid: the view is another artifact's");
155
+ if (!view) {
156
+ db.run(
157
+ "INSERT INTO view (id, artifact_id, version_id, viewer_id, token_id, opened_cursor, opened_at) VALUES (?, ?, ?, ?, NULL, NULL, ?)",
158
+ snapshot.viewId,
159
+ snapshot.artifactId,
160
+ snapshot.versionId,
161
+ viewerId,
162
+ snapshot.at,
163
+ );
164
+ }
165
+ const draft = documentFor(db, snapshot.artifactId, viewerId, true);
166
+ const previous =
167
+ snapshot.previous !== undefined &&
168
+ db.get("SELECT 1 FROM submission WHERE id = ?", snapshot.previous)
169
+ ? snapshot.previous
170
+ : null;
171
+ const origin = {
172
+ server: source.server,
173
+ home: source.home,
174
+ incarnation: source.incarnation,
175
+ cursor: envelope.cursor ?? ("0" as EventOrigin["cursor"]),
176
+ };
177
+ // Its own `submission.created` here, whose cursor is its local position (the order the owner's
178
+ // deliveries replay in); the followed hosted one is never appended itself.
179
+ const localPosition = Number(
180
+ appendEvent(db, {
181
+ artifactId: snapshot.artifactId,
182
+ type: "submission.created",
183
+ actor: { kind: "viewer", id: viewerId },
184
+ causation: { submissionId: snapshot.submissionId },
185
+ payload: {
186
+ submissionId: snapshot.submissionId,
187
+ versionId: snapshot.versionId,
188
+ version: snapshot.version,
189
+ viewId: snapshot.viewId,
190
+ viewerId,
191
+ channel: snapshot.channel,
192
+ epoch: snapshot.epoch,
193
+ staleView: snapshot.staleView,
194
+ digest,
195
+ imported: true,
196
+ },
197
+ }),
198
+ );
199
+ db.run(
200
+ `INSERT INTO submission (id, position, artifact_id, version_id, view_id, viewer_id, channel, policy_json, epoch, scope_key,
201
+ previous_id, draft_document_id, draft_revision, state_revision, latest_version_number, snapshot_json, digest, stale_view,
202
+ request_id, created_at, origin_json)
203
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, ?)`,
204
+ snapshot.submissionId,
205
+ localPosition,
206
+ snapshot.artifactId,
207
+ snapshot.versionId,
208
+ snapshot.viewId,
209
+ viewerId,
210
+ snapshot.channel,
211
+ JSON.stringify(snapshot.policy),
212
+ snapshot.epoch,
213
+ // Hosted answers are their own audience (D165 item 1): they never meet the owner's own links'
214
+ // `once` scopes, and each imported submission is its own key.
215
+ `remote:${source.serverKey}:${snapshot.submissionId}`,
216
+ previous,
217
+ draft.id,
218
+ Number(snapshot.draft.revision),
219
+ snapshot.state ? Number(snapshot.state.revision) : null,
220
+ snapshot.latestVersion ?? null,
221
+ envelope.snapshot,
222
+ digest,
223
+ snapshot.staleView ? 1 : 0,
224
+ snapshot.at,
225
+ originJson(origin),
226
+ );
227
+ const at = new Date().toISOString();
228
+ const owners = input.owners.length > 0 ? [...new Set(input.owners)].sort() : [BUILT_IN_OWNER];
229
+ for (const owner of owners) {
230
+ db.run(
231
+ "INSERT INTO delivery (id, submission_id, position, port_owner, state, attempts, next_attempt_at, updated_at) VALUES (?, ?, ?, ?, 'pending', 0, ?, ?)",
232
+ importedDeliveryId(snapshot.submissionId, owner),
233
+ snapshot.submissionId,
234
+ localPosition,
235
+ owner,
236
+ at,
237
+ at,
238
+ );
239
+ }
240
+ return { accepted: true };
241
+ }
242
+
243
+ /**
244
+ * Types a follow never copies: the owner publishes its versions itself, and its own deliveries
245
+ * record their own outcomes. (A hosted `submission.created` is never appended either: its
246
+ * submission arrives as a delivery, below.)
247
+ */
248
+ const NOT_FOLLOWED = new Set([
249
+ "artifact.created",
250
+ "version.published",
251
+ "submission.retrying",
252
+ "submission.delivered",
253
+ "submission.rejected",
254
+ "submission.undeliverable",
255
+ ]);
256
+
257
+ /** The outcome of copying one page of followed events. */
258
+ export interface FollowOutcome {
259
+ /** Events appended now. */
260
+ readonly appended: number;
261
+ /** Hosted submissions named by a followed `submission.created` that this home lacks. */
262
+ readonly missing: readonly string[];
263
+ }
264
+
265
+ /**
266
+ * Copies a page of the hosted home's events into this home's log, in the caller's transaction:
267
+ * only the artifacts this instance owns, each event once (its origin is unique), with local
268
+ * cursors. A followed `submission.created` this home lacks is reported, so the caller has it
269
+ * delivered again rather than appending a record without its submission.
270
+ */
271
+ export function followEvents(
272
+ db: LedgerDb,
273
+ input: {
274
+ readonly events: readonly EventRecord[];
275
+ readonly source: ImportSource;
276
+ readonly owned: (db: LedgerDb, artifactId: string) => boolean;
277
+ },
278
+ ): FollowOutcome {
279
+ let appended = 0;
280
+ const missing: string[] = [];
281
+ for (const event of input.events) {
282
+ if (event.artifactId === null || !input.owned(db, event.artifactId)) continue;
283
+ if (event.type === "submission.created") {
284
+ const id = event.payload["submissionId"];
285
+ if (typeof id === "string" && !db.get("SELECT 1 FROM submission WHERE id = ?", id))
286
+ missing.push(id);
287
+ continue;
288
+ }
289
+ if (NOT_FOLLOWED.has(event.type)) continue;
290
+ // A run this home ran for the hosted home records its own events (relayed); the hosted copy
291
+ // of them would say each twice (Opus review of WP-29). Events of a run that never reached this
292
+ // home (it waited, failed while the owner was offline, was cancelled unsent) are copied.
293
+ if (event.type.startsWith("action.")) {
294
+ const runId = (event.payload as { runId?: unknown } | undefined)?.runId;
295
+ if (typeof runId === "string" && db.get("SELECT 1 FROM action_run WHERE id = ?", runId)) {
296
+ continue;
297
+ }
298
+ }
299
+ const origin: EventOrigin = {
300
+ server: input.source.server,
301
+ home: input.source.home,
302
+ incarnation: input.source.incarnation,
303
+ cursor: event.cursor,
304
+ };
305
+ if (db.get("SELECT 1 FROM event WHERE origin_json = ?", originJson(origin))) continue;
306
+ appendEvent(db, {
307
+ artifactId: event.artifactId,
308
+ type: event.type,
309
+ actor: event.actor,
310
+ ...(event.causation !== undefined ? { causation: event.causation } : {}),
311
+ payload: event.payload,
312
+ origin,
313
+ });
314
+ appended += 1;
315
+ }
316
+ return { appended, missing };
317
+ }