@mostra/runtime 0.9.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-EnaZPs14.js → instance-FExcyENK.js} +3341 -396
  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 +8 -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-EnaZPs14.js.map +0 -1
@@ -17,6 +17,7 @@ import {
17
17
  type CapabilityScope,
18
18
  type CarryOver,
19
19
  type ControlsPolicy,
20
+ type Cursor,
20
21
  createDiagnostic,
21
22
  type DeliveryCounts,
22
23
  type EventFilter,
@@ -36,7 +37,9 @@ import {
36
37
  refusal,
37
38
  resultsGetMethod,
38
39
  type StreamSnapshot,
40
+ type SubmissionEnvelope,
39
41
  type SubmissionSummary,
42
+ type SubmissionsDeliverResult,
40
43
  type SubmitChannel,
41
44
  scopeAllows,
42
45
  stateGetMethod,
@@ -57,6 +60,7 @@ import {
57
60
  liveFields,
58
61
  replayedMutation,
59
62
  } from "./fields.ts";
63
+ import { type ImportSource, importSubmission } from "./imports.ts";
60
64
  import { type HostConnections, Outbox } from "./outbox.ts";
61
65
  import { buildResults, CHOICE, resultsMarkdown, submissionFor } from "./results.ts";
62
66
  import {
@@ -81,6 +85,7 @@ import {
81
85
  orphansOf,
82
86
  type Snapshot,
83
87
  type SubmissionRow,
88
+ SubmitConflict,
84
89
  submissionSummary,
85
90
  submit,
86
91
  } from "./submissions.ts";
@@ -100,10 +105,23 @@ import { waitFor } from "./wait.ts";
100
105
 
101
106
  export { createEphemeralBus, type EphemeralBus } from "./ephemeral.ts";
102
107
  export { appendEvent, compactEvents, redactEvents } from "./events.ts";
108
+ export { followEvents, type ImportSource, importedDeliveryId } from "./imports.ts";
103
109
  export type { HostConnections } from "./outbox.ts";
104
110
  export { policyInForce } from "./policy.ts";
105
- export type { RunEnd, RunFlush, RunOutput, RunRow } from "./runs.ts";
111
+ export {
112
+ appendRunOutput,
113
+ finishRun,
114
+ markRunning,
115
+ markUnknown,
116
+ markWaiting,
117
+ type RunEnd,
118
+ type RunFlush,
119
+ type RunOutput,
120
+ type RunRow,
121
+ runState,
122
+ } from "./runs.ts";
106
123
  export { SubmitConflict } from "./submissions.ts";
124
+ export { tallyField, tallyState } from "./tally.ts";
107
125
 
108
126
  /** How the interaction core finds an artifact a host names. */
109
127
  export interface InteractionArtifacts {
@@ -132,8 +150,30 @@ export interface InteractionOptions {
132
150
  readonly coverage: (versionId: string) => (fieldId: string) => boolean;
133
151
  /** How long a host has to answer a port call (30 s; tests shorten it). */
134
152
  readonly portTimeoutMs?: number;
153
+ /**
154
+ * Who a submission of this artifact is delivered to, instead of every registered or expected
155
+ * host: on a hosted home, the artifact's owner link alone, connected or not (D165, after the Opus
156
+ * review). `undefined` keeps D105's rule.
157
+ */
158
+ readonly deliveryOwners?: (artifactId: string) => readonly string[] | undefined;
159
+ /** Whether deliveries carry the stored snapshot: a hosted home's do (D165 item 1). */
160
+ readonly deliverSnapshots?: boolean;
161
+ /**
162
+ * Whether pages see only that an answer was sent (D165 item 1a, IN-13 for hosted links): a
163
+ * submission's `delivery` reads `delivered` once it committed, without `deliveries`, and pages
164
+ * get no delivery events. The owner, its agent and hosts keep every delivery state.
165
+ */
166
+ readonly sentOnly?: boolean;
135
167
  }
136
168
 
169
+ /** The delivery events only the owner, its agent and hosts see on a hosted home (D165 item 1a). */
170
+ const DELIVERY_EVENTS = new Set([
171
+ "submission.retrying",
172
+ "submission.delivered",
173
+ "submission.rejected",
174
+ "submission.undeliverable",
175
+ ]);
176
+
137
177
  /** A browser session as the interaction core sees it: who it acts as. */
138
178
  export interface PageIdentity {
139
179
  readonly artifactId: string;
@@ -185,6 +225,16 @@ export interface Interaction {
185
225
  readonly ops: readonly FieldOp[];
186
226
  },
187
227
  ): MutationResult;
228
+ /**
229
+ * Stores a submission its hosted home delivered to this owner instance, with its local
230
+ * deliveries, in one transaction (D165 item 1), and answers as a host answers a delivery.
231
+ */
232
+ importSubmission(envelope: SubmissionEnvelope, source: ImportSource): SubmissionsDeliverResult;
233
+ /**
234
+ * A submission as its delivery to `owner` carries it, with its snapshot (a hosted home's
235
+ * `hosted/submission`, FAILURE_MODEL §11.2); `undefined` when `owner` has no delivery of it.
236
+ */
237
+ envelopeFor(submissionId: string, owner: string): SubmissionEnvelope | undefined;
188
238
  /** A viewer's submit (IN-05); `SubmitConflict` under a closed `once`. */
189
239
  submit(
190
240
  page: PageIdentity,
@@ -288,6 +338,8 @@ export interface Interaction {
288
338
  openRuns(versionId?: string): RunRow[];
289
339
  /** A run's state now. */
290
340
  runState(runId: string): RunState | undefined;
341
+ /** A run's row, for the actions module (a relayed run, D165 item 4). */
342
+ runRow(runId: string): RunRow | undefined;
291
343
  /** `signal()` from server code: `signal.raised`, source `action`, the run as cause (AC-05). */
292
344
  serverSignal(
293
345
  artifactId: string,
@@ -341,6 +393,11 @@ export interface Interaction {
341
393
  * session reports what its preview's submits would deliver (D140 item 12). Returns the stop.
342
394
  */
343
395
  onSubmission(listener: (results: Results) => void): () => void;
396
+ /**
397
+ * Hears, once a submission commits, which of its artifact's tallied fields it counted (D165
398
+ * item 12), so their viewers are sent the new counts. Returns the stop.
399
+ */
400
+ onTallied(listener: (artifactId: string, fields: readonly string[]) => void): () => void;
344
401
  /** How many host subscriptions are open. */
345
402
  subscriptionCount(): number;
346
403
  }
@@ -449,6 +506,24 @@ function runVisible(row: RunRow, page: PageIdentity): boolean {
449
506
  /** Creates the interaction core. */
450
507
 
451
508
  export function createInteraction(options: InteractionOptions): Interaction {
509
+ /** A submission as a page gets it: on a hosted home, sent and nothing about its delivery. */
510
+ const forPage = (summary: SubmissionSummary): SubmissionSummary => {
511
+ if (!options.sentOnly) return summary;
512
+ const { deliveries: _deliveries, ...sent } = summary;
513
+ return { ...sent, delivery: "delivered" };
514
+ };
515
+ /** Runs a page's write, giving a conflict's submission as the page gets it. */
516
+ const asPage = <T>(write: () => T): T => {
517
+ try {
518
+ return write();
519
+ } catch (error) {
520
+ if (options.sentOnly && error instanceof SubmitConflict) {
521
+ throw new SubmitConflict(error.diagnostic.message, forPage(error.submission));
522
+ }
523
+ throw error;
524
+ }
525
+ };
526
+ const tallyListeners = new Set<(artifactId: string, fields: readonly string[]) => void>();
452
527
  const { ledger, log, hosts } = options;
453
528
  const outbox = new Outbox({
454
529
  ledger,
@@ -457,6 +532,7 @@ export function createInteraction(options: InteractionOptions): Interaction {
457
532
  expected: options.expectedHosts,
458
533
  faults: options.faults,
459
534
  ...(options.portTimeoutMs !== undefined ? { portTimeoutMs: options.portTimeoutMs } : {}),
535
+ ...(options.deliverSnapshots ? { snapshots: true } : {}),
460
536
  });
461
537
  const subscriptions = new Subscriptions({
462
538
  ledger,
@@ -541,7 +617,7 @@ export function createInteraction(options: InteractionOptions): Interaction {
541
617
  const replay = replayedMutation(db, mutation);
542
618
  if (replay) return { result: replay, changed: false, replayed: true };
543
619
  if (input.scope === "viewer") {
544
- assertDraftOpen(db, page.artifactId, page.viewerId);
620
+ asPage(() => assertDraftOpen(db, page.artifactId, page.viewerId));
545
621
  if (input.ops.some((op) => CHOICE.test(op.id))) {
546
622
  // A choice needs the `review` scope however it is written, as the trusted Choose
547
623
  // does (D97; Claude review finding 7)…
@@ -569,20 +645,77 @@ export function createInteraction(options: InteractionOptions): Interaction {
569
645
  outbox.mirror(page.artifactId, page.viewerId);
570
646
  return result;
571
647
  },
572
- submit(page, input) {
573
- const owners = outbox.owners();
574
- const outcome = ledger.write((db) =>
575
- submit(db, {
576
- artifactId: page.artifactId,
577
- viewerId: page.viewerId,
578
- ...(page.tokenId !== undefined ? { tokenId: page.tokenId } : {}),
579
- viewId: input.viewId,
580
- expectedRevision: input.expectedRevision,
581
- channel: input.channel,
648
+ importSubmission(envelope, source) {
649
+ const owners = options.deliveryOwners?.(envelope.artifactId) ?? outbox.owners();
650
+ const answer = ledger.write((db) =>
651
+ importSubmission(db, {
652
+ envelope,
653
+ source,
582
654
  owners,
583
- covers: options.coverage,
655
+ owned: (inner, artifactId) =>
656
+ inner.get(
657
+ "SELECT 1 FROM hosted_artifact WHERE artifact_id = ? AND server = ?",
658
+ artifactId,
659
+ source.server,
660
+ ) !== undefined,
584
661
  }),
585
662
  );
663
+ log.info("interaction.imported", {
664
+ artifactId: envelope.artifactId,
665
+ submissionId: envelope.submissionId,
666
+ accepted: answer.accepted,
667
+ });
668
+ return answer;
669
+ },
670
+ envelopeFor(submissionId, owner) {
671
+ return ledger.read((db) => {
672
+ const delivery = db.get<{ id: string; attempts: number }>(
673
+ "SELECT id, attempts FROM delivery WHERE submission_id = ? AND port_owner = ?",
674
+ submissionId,
675
+ owner,
676
+ );
677
+ const submission = db.get<SubmissionRow>(
678
+ "SELECT * FROM submission WHERE id = ?",
679
+ submissionId,
680
+ );
681
+ if (!delivery || !submission) return undefined;
682
+ return {
683
+ kind: "submission",
684
+ deliveryId: delivery.id,
685
+ submissionId: submission.id,
686
+ artifactId: submission.artifact_id,
687
+ attempt: Math.max(1, delivery.attempts),
688
+ results: buildResults(db, submission),
689
+ snapshot: submission.snapshot_json,
690
+ cursor: String(submission.position) as Cursor,
691
+ };
692
+ });
693
+ },
694
+ submit(page, input) {
695
+ const owners = options.deliveryOwners?.(page.artifactId) ?? outbox.owners();
696
+ const outcome = asPage(() =>
697
+ ledger.write((db) =>
698
+ submit(db, {
699
+ artifactId: page.artifactId,
700
+ viewerId: page.viewerId,
701
+ ...(page.tokenId !== undefined ? { tokenId: page.tokenId } : {}),
702
+ viewId: input.viewId,
703
+ expectedRevision: input.expectedRevision,
704
+ channel: input.channel,
705
+ owners,
706
+ covers: options.coverage,
707
+ }),
708
+ ),
709
+ );
710
+ if (outcome.tallied) {
711
+ for (const listener of tallyListeners) {
712
+ try {
713
+ listener(page.artifactId, outcome.tallied);
714
+ } catch (error) {
715
+ log.error("interaction.tally_listener_failed", { error });
716
+ }
717
+ }
718
+ }
586
719
  if (outcome.created) {
587
720
  log.info("interaction.submitted", {
588
721
  artifactId: page.artifactId,
@@ -599,8 +732,8 @@ export function createInteraction(options: InteractionOptions): Interaction {
599
732
  );
600
733
  return row ? submissionSummary(db, row) : undefined;
601
734
  });
602
- if (!fresh) return outcome.submission;
603
- return outcome.submission.duplicate ? { ...fresh, duplicate: true } : fresh;
735
+ if (!fresh) return forPage(outcome.submission);
736
+ return forPage(outcome.submission.duplicate ? { ...fresh, duplicate: true } : fresh);
604
737
  },
605
738
  choose(page, input) {
606
739
  const actor = pageActor(page);
@@ -627,7 +760,7 @@ export function createInteraction(options: InteractionOptions): Interaction {
627
760
  };
628
761
  const replay = replayedMutation(db, mutation);
629
762
  if (replay) return { result: replay, changed: false, replayed: true };
630
- assertDraftOpen(db, page.artifactId, page.viewerId);
763
+ asPage(() => assertDraftOpen(db, page.artifactId, page.viewerId));
631
764
  return applyMutation(db, mutation);
632
765
  });
633
766
  if (outcome.changed) outbox.mirror(page.artifactId, page.viewerId);
@@ -710,7 +843,7 @@ export function createInteraction(options: InteractionOptions): Interaction {
710
843
  const state = documentSnapshot(db, page.artifactId, null);
711
844
  return { ...state, fields: fieldsForPage(state.fields, page.viewerId) };
712
845
  })(),
713
- ...(latestOwn ? { submission: submissionSummary(db, latestOwn) } : {}),
846
+ ...(latestOwn ? { submission: forPage(submissionSummary(db, latestOwn)) } : {}),
714
847
  ...(() => {
715
848
  // The latest version, so a page that missed its `version.published` learns of it.
716
849
  const latest = db.get<{ id: string; number: number }>(
@@ -727,6 +860,15 @@ export function createInteraction(options: InteractionOptions): Interaction {
727
860
  // Read in pages until enough visible events or the end, so other viewers' events never
728
861
  // stall a page.
729
862
  return ledger.read((db) => {
863
+ // A cursor above the head was read from a home since restored to an earlier copy (§18.2):
864
+ // the page starts again from a fresh snapshot, never from an empty tail.
865
+ if (after > latestCursor(db)) {
866
+ throw new RpcError(
867
+ createDiagnostic("MOSTRA_HOST_CURSOR_COMPACTED", {
868
+ message: "The page's cursor is past this home's head; it reads a fresh snapshot.",
869
+ }),
870
+ );
871
+ }
730
872
  const events: EventRecord[] = [];
731
873
  let cursor = after;
732
874
  const runs = new Map<string, RunRow | undefined>();
@@ -743,6 +885,7 @@ export function createInteraction(options: InteractionOptions): Interaction {
743
885
  for (const event of read.events) {
744
886
  if (events.length === limit) return { events, cursor: String(cursor) };
745
887
  cursor = Number(event.cursor);
888
+ if (options.sentOnly && DELIVERY_EVENTS.has(event.type)) continue;
746
889
  if (visibleTo(event, page, runOf)) events.push(eventForPage(event, page.viewerId));
747
890
  }
748
891
  cursor = Math.max(cursor, Number(read.cursor));
@@ -780,7 +923,10 @@ export function createInteraction(options: InteractionOptions): Interaction {
780
923
  ? { baseRevision: Number(params.baseRevision) }
781
924
  : {}),
782
925
  ops: params.ops,
783
- actor: clientActor(session, params.as),
926
+ actor:
927
+ params.causation !== undefined
928
+ ? { kind: "agent", id: params.causation.runId }
929
+ : clientActor(session, params.as),
784
930
  }).result,
785
931
  );
786
932
  }),
@@ -828,7 +974,7 @@ export function createInteraction(options: InteractionOptions): Interaction {
828
974
  ],
829
975
  connected(session) {
830
976
  if (session.ports.has("submissions") && session.client)
831
- outbox.registered(session.client.name);
977
+ outbox.registered(session.link?.instanceId ?? session.client.name);
832
978
  },
833
979
  disconnected(session) {
834
980
  subscriptions.closed(session.id);
@@ -900,6 +1046,9 @@ export function createInteraction(options: InteractionOptions): Interaction {
900
1046
  openRuns(versionId) {
901
1047
  return ledger.read((db) => openRuns(db, versionId));
902
1048
  },
1049
+ runRow(runId) {
1050
+ return ledger.read((db) => db.get<RunRow>("SELECT * FROM action_run WHERE id = ?", runId));
1051
+ },
903
1052
  runState(runId) {
904
1053
  return ledger.read((db) => {
905
1054
  const row = db.get<RunRow>("SELECT * FROM action_run WHERE id = ?", runId);
@@ -1016,6 +1165,10 @@ export function createInteraction(options: InteractionOptions): Interaction {
1016
1165
  }
1017
1166
  });
1018
1167
  },
1168
+ onTallied(listener) {
1169
+ tallyListeners.add(listener);
1170
+ return () => tallyListeners.delete(listener);
1171
+ },
1019
1172
  subscriptionCount: () => subscriptions.size,
1020
1173
  };
1021
1174
  }
@@ -8,6 +8,7 @@
8
8
  * delivery the host acknowledged but Mostra didn't record goes out again with the same ID.
9
9
  */
10
10
  import {
11
+ type Cursor,
11
12
  type DeliveryState,
12
13
  type DraftMirror,
13
14
  MAX_LINE_LENGTH,
@@ -61,6 +62,11 @@ export interface OutboxOptions {
61
62
  readonly now?: () => number;
62
63
  /** How long a host has to answer a port call; default {@link PORT_CALL_TIMEOUT_MS}. */
63
64
  readonly portTimeoutMs?: number;
65
+ /**
66
+ * Whether envelopes carry the stored snapshot: a hosted home's do, so its owner instance keeps
67
+ * the same submission (D165 item 1).
68
+ */
69
+ readonly snapshots?: boolean;
64
70
  }
65
71
 
66
72
  interface DeliveryRow {
@@ -260,6 +266,9 @@ export class Outbox {
260
266
  artifactId: submission.artifact_id,
261
267
  attempt,
262
268
  results: buildResults(db, submission),
269
+ ...(this.#options.snapshots
270
+ ? { snapshot: submission.snapshot_json, cursor: String(submission.position) as Cursor }
271
+ : {}),
263
272
  };
264
273
  return envelope;
265
274
  });
@@ -3,7 +3,13 @@
3
3
  * Everything comes from the immutable submission row, its snapshot and the version it names, plus
4
4
  * the deliveries' current states; never from the live draft (IN-06).
5
5
  */
6
- import type { ArtifactLink, ArtifactManifest, DeliveryStatus, Results } from "@mostra/protocol";
6
+ import type {
7
+ ArtifactLink,
8
+ ArtifactManifest,
9
+ DeliveryStatus,
10
+ EventOrigin,
11
+ Results,
12
+ } from "@mostra/protocol";
7
13
  import { createDiagnostic, RpcError } from "@mostra/protocol";
8
14
  import type { LedgerDb } from "../ledger/index.ts";
9
15
  import { storedPolicy } from "./policy.ts";
@@ -164,6 +170,7 @@ export function buildResults(db: LedgerDb, row: SubmissionRow): Results {
164
170
  digest: row.digest,
165
171
  delivery: overallDelivery(deliveries),
166
172
  deliveries,
173
+ ...(row.origin_json ? { origin: JSON.parse(row.origin_json) as EventOrigin } : {}),
167
174
  },
168
175
  answers: nestFields(draftFields),
169
176
  fields: [
@@ -144,9 +144,58 @@ export function createOrJoinRun(db: LedgerDb, input: NewRun): { row: RunRow; joi
144
144
  };
145
145
  }
146
146
 
147
- /** Moves a queued run to `running`, when its worker has it. */
147
+ /** Moves a queued (or, on a remote server, waiting) run to `running`, when its worker has it. */
148
148
  export function markRunning(db: LedgerDb, runId: string): void {
149
- db.run("UPDATE action_run SET status = 'running' WHERE id = ? AND status = 'queued'", runId);
149
+ db.run(
150
+ "UPDATE action_run SET status = 'running' WHERE id = ? AND status IN ('queued', 'waiting')",
151
+ runId,
152
+ );
153
+ }
154
+
155
+ /**
156
+ * A relayed run waits for its owner's instance (D165 item 4): `waiting`, with `action.waiting`.
157
+ * Returns whether it moved (a queued run only).
158
+ */
159
+ export function markWaiting(db: LedgerDb, runId: string): boolean {
160
+ const row = db.get<RunRow>("SELECT * FROM action_run WHERE id = ?", runId);
161
+ if (row?.status !== "queued") return false;
162
+ db.run("UPDATE action_run SET status = 'waiting' WHERE id = ?", runId);
163
+ appendEvent(db, {
164
+ artifactId: row.artifact_id,
165
+ type: "action.waiting",
166
+ actor: { kind: "mostra" },
167
+ causation: { runId },
168
+ payload: { runId, action: row.action },
169
+ });
170
+ return true;
171
+ }
172
+
173
+ /**
174
+ * A relayed run whose owner never reported its end within the offline limit, or no longer knows
175
+ * it (D165 item 4): `unknown`, with `action.unknown`. It may have taken effect, so it is never
176
+ * `failed`; the owner's later report replaces it once (a trigger). Returns whether it moved.
177
+ */
178
+ export function markUnknown(db: LedgerDb, runId: string): boolean {
179
+ const row = db.get<RunRow>("SELECT * FROM action_run WHERE id = ?", runId);
180
+ if (!row || (row.status !== "queued" && row.status !== "running" && row.status !== "waiting"))
181
+ return false;
182
+ db.run(
183
+ "UPDATE action_run SET status = 'unknown', reason = 'owner-unreachable', error_json = ? WHERE id = ?",
184
+ JSON.stringify({
185
+ code: "MOSTRA_REMOTE_OWNER_OFFLINE",
186
+ message:
187
+ "Its owner's machine never said how it ended, so it may have taken effect; it shows here if the owner reports.",
188
+ }),
189
+ runId,
190
+ );
191
+ appendEvent(db, {
192
+ artifactId: row.artifact_id,
193
+ type: "action.unknown",
194
+ actor: { kind: "mostra" },
195
+ causation: { runId },
196
+ payload: { runId, action: row.action },
197
+ });
198
+ return true;
150
199
  }
151
200
 
152
201
  /** What a running run produced since the last flush. */
@@ -238,6 +287,7 @@ export function finishRun(db: LedgerDb, runId: string, end: RunEnd): RunRow | un
238
287
  const row = db.get<RunRow>("SELECT * FROM action_run WHERE id = ?", runId);
239
288
  if (!row || isFinalRunStatus(row.status)) return row;
240
289
  const finishedAt = new Date().toISOString();
290
+ // An `unknown` run's reported end replaces its reason and error too (D165 item 4).
241
291
  db.run(
242
292
  "UPDATE action_run SET status = ?, reason = ?, error_json = ?, finished_at = ? WHERE id = ?",
243
293
  end.status,
@@ -26,6 +26,7 @@ import { appendEvent } from "./events.ts";
26
26
  import { documentFor, type FieldRow } from "./fields.ts";
27
27
  import { storedPolicy } from "./policy.ts";
28
28
  import { raiseSubmitSignal, SUBMIT_SIGNAL } from "./signals.ts";
29
+ import { countSubmission } from "./tally.ts";
29
30
  import { type ViewRow, viewControls, viewer as viewerById, viewFor } from "./viewers.ts";
30
31
 
31
32
  /** The most signals a snapshot keeps: the view's newest. */
@@ -124,6 +125,8 @@ export interface SubmissionRow {
124
125
  readonly digest: string;
125
126
  readonly stale_view: number;
126
127
  readonly created_at: string;
128
+ /** For a submission imported from a hosted home: where it came from (DATA_MODEL §7.3). */
129
+ readonly origin_json?: string | null;
127
130
  }
128
131
 
129
132
  interface DeliveryRow {
@@ -310,6 +313,8 @@ export interface SubmitOutcome {
310
313
  readonly submission: SubmissionSummary;
311
314
  /** `false` when it returned an earlier submission of the same view and revision (D22). */
312
315
  readonly created: boolean;
316
+ /** The tallied fields whose counts this submission grew (D165 item 12). */
317
+ readonly tallied?: readonly string[];
313
318
  }
314
319
 
315
320
  /**
@@ -552,6 +557,13 @@ export function submit(db: LedgerDb, input: SubmitInput): SubmitOutcome {
552
557
  staleView ? 1 : 0,
553
558
  at,
554
559
  );
560
+ // Counts by choice grow in the same transaction, so a count is never ahead of, or behind, the
561
+ // submissions it counts (D165 item 12).
562
+ const tallied = countSubmission(db, {
563
+ artifactId: input.artifactId,
564
+ versionId: view.version_id,
565
+ fields: snapshot.draft.fields,
566
+ });
555
567
  // The next round starts with the same values (D103).
556
568
  if (policy.policy === "epochs") {
557
569
  db.run("UPDATE document SET epoch = ? WHERE id = ?", epoch + 1, draft.id);
@@ -581,5 +593,9 @@ export function submit(db: LedgerDb, input: SubmitInput): SubmitOutcome {
581
593
  "SELECT * FROM submission WHERE id = ?",
582
594
  submissionId,
583
595
  ) as SubmissionRow;
584
- return { submission: submissionSummary(db, row), created: true };
596
+ return {
597
+ submission: submissionSummary(db, row),
598
+ created: true,
599
+ ...(tallied.length > 0 ? { tallied } : {}),
600
+ };
585
601
  }
@@ -0,0 +1,129 @@
1
+ /**
2
+ * Counts by choice (D165 item 12, RM-07; DATA_MODEL §7.4, INTERFACES §18.4). An artifact that
3
+ * names a fixed-choice field in its manifest's `tally` gets a count of each choice, grown inside the
4
+ * submit transaction, one more for the choice the new submission holds, and read by viewers under
5
+ * the reserved live key `$tally/<field>`. Nothing else of a submission reaches viewers this way: a
6
+ * value outside the listed choices counts nothing, so free text is never shown, and below the
7
+ * entry's `minTotal` viewers see only the total.
8
+ */
9
+ import {
10
+ ArtifactManifest,
11
+ type Batches,
12
+ TALLY_LIVE_PREFIX,
13
+ type TallySpec,
14
+ type TallyValue,
15
+ } from "@mostra/protocol";
16
+ import type { LedgerDb } from "../ledger/index.ts";
17
+
18
+ /** The tally entries of a version's manifest; none when it has none or can't be read. */
19
+ export function tallySpecs(db: LedgerDb, versionId: string): readonly TallySpec[] {
20
+ const row = db.get<{ manifest_json: string }>(
21
+ "SELECT manifest_json FROM version WHERE id = ?",
22
+ versionId,
23
+ );
24
+ if (!row) return [];
25
+ try {
26
+ const parsed = ArtifactManifest.safeParse(JSON.parse(row.manifest_json));
27
+ return parsed.success ? (parsed.data.tally ?? []) : [];
28
+ } catch {
29
+ return [];
30
+ }
31
+ }
32
+
33
+ /**
34
+ * Counts a new submission, in its submit transaction: for each tally of the version the
35
+ * submission names, one more for the choice its draft holds for the field. Returns the fields whose
36
+ * counts grew, so their viewers can be told after the commit.
37
+ */
38
+ export function countSubmission(
39
+ db: LedgerDb,
40
+ input: {
41
+ readonly artifactId: string;
42
+ readonly versionId: string;
43
+ /** The submission's draft fields, as its snapshot holds them. */
44
+ readonly fields: Readonly<Record<string, { readonly value: unknown }>>;
45
+ },
46
+ ): string[] {
47
+ const grown: string[] = [];
48
+ for (const spec of tallySpecs(db, input.versionId)) {
49
+ const value = Object.hasOwn(input.fields, spec.field)
50
+ ? input.fields[spec.field]?.value
51
+ : undefined;
52
+ if (typeof value !== "string" || !spec.choices.includes(value)) continue;
53
+ // A row is counted, never replaced (a trigger), so the first answer inserts it and every
54
+ // later one adds to it; the count never goes down (a trigger too).
55
+ const updated = db.run(
56
+ "UPDATE tally SET count = count + 1 WHERE artifact_id = ? AND field_id = ? AND choice = ?",
57
+ input.artifactId,
58
+ spec.field,
59
+ value,
60
+ );
61
+ if (updated.changes === 0) {
62
+ db.run(
63
+ "INSERT INTO tally (artifact_id, field_id, choice, count) VALUES (?, ?, ?, 1)",
64
+ input.artifactId,
65
+ spec.field,
66
+ value,
67
+ );
68
+ }
69
+ grown.push(spec.field);
70
+ }
71
+ return grown;
72
+ }
73
+
74
+ /** The field a tally's live key reads, or `undefined` for any other key. */
75
+ export function tallyField(key: string): string | undefined {
76
+ return key.startsWith(TALLY_LIVE_PREFIX) ? key.slice(TALLY_LIVE_PREFIX.length) : undefined;
77
+ }
78
+
79
+ /** A tally as a live source reads it: its value, and a revision that only grows. */
80
+ export interface TallyState {
81
+ /** The total counted for the field, as a decimal string: it grows with every count. */
82
+ readonly revision: string;
83
+ readonly value: TallyValue;
84
+ /** The value as serializer batches, as every live value travels. */
85
+ readonly batches: Batches;
86
+ }
87
+
88
+ /**
89
+ * The tally of `field` as viewers see it, by the artifact's latest version's entry: each listed
90
+ * choice's count (a choice no one chose is 0), and the total, or only the total below the entry's
91
+ * `minTotal`. `undefined` when the latest version tallies no such field.
92
+ */
93
+ export function tallyState(
94
+ db: LedgerDb,
95
+ artifactId: string,
96
+ field: string,
97
+ ): TallyState | undefined {
98
+ const latest = db.get<{ latest_version_id: string | null }>(
99
+ "SELECT latest_version_id FROM artifact WHERE id = ?",
100
+ artifactId,
101
+ )?.latest_version_id;
102
+ if (!latest) return undefined;
103
+ const spec = tallySpecs(db, latest).find((entry) => entry.field === field);
104
+ if (!spec) return undefined;
105
+ const rows = db.all<{ choice: string; count: number }>(
106
+ "SELECT choice, count FROM tally WHERE artifact_id = ? AND field_id = ?",
107
+ artifactId,
108
+ field,
109
+ );
110
+ const byChoice = new Map(rows.map((row) => [row.choice, row.count]));
111
+ // Every answer ever counted for the field: an earlier version's choices included, so the
112
+ // revision only grows whatever a later version lists.
113
+ const counted = rows.reduce((sum, row) => sum + row.count, 0);
114
+ const counts: Record<string, number> = {};
115
+ let total = 0;
116
+ for (const choice of spec.choices) {
117
+ const count = byChoice.get(choice) ?? 0;
118
+ // defineProperty keeps a choice such as `__proto__` an own key.
119
+ Object.defineProperty(counts, choice, {
120
+ value: count,
121
+ enumerable: true,
122
+ writable: true,
123
+ configurable: true,
124
+ });
125
+ total += count;
126
+ }
127
+ const value: TallyValue = total < (spec.minTotal ?? 0) ? { total } : { counts, total };
128
+ return { revision: String(counted), value, batches: [[{ c: 0, v: value }]] };
129
+ }