@mostra/protocol 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 (224) hide show
  1. package/dist/actions.d.ts +30 -4
  2. package/dist/actions.d.ts.map +1 -1
  3. package/dist/actions.js +14 -4
  4. package/dist/actions.js.map +1 -1
  5. package/dist/artifact.d.ts +2 -1
  6. package/dist/artifact.d.ts.map +1 -1
  7. package/dist/artifact.js +2 -1
  8. package/dist/artifact.js.map +1 -1
  9. package/dist/browser.d.ts +5 -0
  10. package/dist/browser.d.ts.map +1 -1
  11. package/dist/browser.js +7 -2
  12. package/dist/browser.js.map +1 -1
  13. package/dist/capability.d.ts +0 -9
  14. package/dist/capability.d.ts.map +1 -1
  15. package/dist/capability.js +1 -17
  16. package/dist/capability.js.map +1 -1
  17. package/dist/diagnostics/codes/artifact.d.ts +1 -1
  18. package/dist/diagnostics/codes/artifact.d.ts.map +1 -1
  19. package/dist/diagnostics/codes/artifact.js +45 -1
  20. package/dist/diagnostics/codes/artifact.js.map +1 -1
  21. package/dist/diagnostics/codes/env.d.ts +1 -1
  22. package/dist/diagnostics/codes/env.d.ts.map +1 -1
  23. package/dist/diagnostics/codes/env.js +12 -1
  24. package/dist/diagnostics/codes/env.js.map +1 -1
  25. package/dist/diagnostics/codes/home.d.ts +1 -1
  26. package/dist/diagnostics/codes/home.d.ts.map +1 -1
  27. package/dist/diagnostics/codes/home.js +12 -1
  28. package/dist/diagnostics/codes/home.js.map +1 -1
  29. package/dist/diagnostics/codes/index.d.ts +3 -2
  30. package/dist/diagnostics/codes/index.d.ts.map +1 -1
  31. package/dist/diagnostics/codes/index.js +3 -1
  32. package/dist/diagnostics/codes/index.js.map +1 -1
  33. package/dist/diagnostics/codes/remote.d.ts +8 -0
  34. package/dist/diagnostics/codes/remote.d.ts.map +1 -0
  35. package/dist/diagnostics/codes/remote.js +99 -0
  36. package/dist/diagnostics/codes/remote.js.map +1 -0
  37. package/dist/diagnostics/codes/submit.js +3 -3
  38. package/dist/diagnostics/codes/submit.js.map +1 -1
  39. package/dist/diagnostics/diagnostic.d.ts +1 -1
  40. package/dist/diagnostics/diagnostic.d.ts.map +1 -1
  41. package/dist/diagnostics/diagnostic.js +2 -1
  42. package/dist/diagnostics/diagnostic.js.map +1 -1
  43. package/dist/duration.d.ts +13 -0
  44. package/dist/duration.d.ts.map +1 -0
  45. package/dist/duration.js +27 -0
  46. package/dist/duration.js.map +1 -0
  47. package/dist/hygiene.d.ts +4 -1
  48. package/dist/hygiene.d.ts.map +1 -1
  49. package/dist/hygiene.js +4 -0
  50. package/dist/hygiene.js.map +1 -1
  51. package/dist/ids.d.ts +17 -1
  52. package/dist/ids.d.ts.map +1 -1
  53. package/dist/ids.js +9 -1
  54. package/dist/ids.js.map +1 -1
  55. package/dist/index.d.ts +30 -8
  56. package/dist/index.js +30 -8
  57. package/dist/interaction.d.ts +28 -2
  58. package/dist/interaction.d.ts.map +1 -1
  59. package/dist/interaction.js +20 -5
  60. package/dist/interaction.js.map +1 -1
  61. package/dist/manifest.d.ts +59 -14
  62. package/dist/manifest.d.ts.map +1 -1
  63. package/dist/manifest.js +63 -15
  64. package/dist/manifest.js.map +1 -1
  65. package/dist/methods/artifact/export.d.ts +40 -0
  66. package/dist/methods/artifact/export.d.ts.map +1 -0
  67. package/dist/methods/artifact/export.js +36 -0
  68. package/dist/methods/artifact/export.js.map +1 -0
  69. package/dist/methods/artifact/import.d.ts +23 -0
  70. package/dist/methods/artifact/import.d.ts.map +1 -0
  71. package/dist/methods/artifact/import.js +25 -0
  72. package/dist/methods/artifact/import.js.map +1 -0
  73. package/dist/methods/artifact/publish.d.ts +2 -1
  74. package/dist/methods/artifact/publish.d.ts.map +1 -1
  75. package/dist/methods/artifact/publish.js +1 -1
  76. package/dist/methods/hosted/push.d.ts +76 -0
  77. package/dist/methods/hosted/push.d.ts.map +1 -0
  78. package/dist/methods/hosted/push.js +71 -0
  79. package/dist/methods/hosted/push.js.map +1 -0
  80. package/dist/methods/hosted/submission.d.ts +18 -0
  81. package/dist/methods/hosted/submission.d.ts.map +1 -0
  82. package/dist/methods/hosted/submission.js +23 -0
  83. package/dist/methods/hosted/submission.js.map +1 -0
  84. package/dist/methods/index.d.ts.map +1 -1
  85. package/dist/methods/index.js +38 -2
  86. package/dist/methods/index.js.map +1 -1
  87. package/dist/methods/instance/status.d.ts +3 -0
  88. package/dist/methods/instance/status.d.ts.map +1 -1
  89. package/dist/methods/instance/status.js +3 -1
  90. package/dist/methods/instance/status.js.map +1 -1
  91. package/dist/methods/mostra/initialize.d.ts +17 -3
  92. package/dist/methods/mostra/initialize.d.ts.map +1 -1
  93. package/dist/methods/mostra/initialize.js +11 -3
  94. package/dist/methods/mostra/initialize.js.map +1 -1
  95. package/dist/methods/port/relay-call.d.ts +33 -0
  96. package/dist/methods/port/relay-call.d.ts.map +1 -0
  97. package/dist/methods/port/relay-call.js +31 -0
  98. package/dist/methods/port/relay-call.js.map +1 -0
  99. package/dist/methods/port/relay-cancel.d.ts +16 -0
  100. package/dist/methods/port/relay-cancel.d.ts.map +1 -0
  101. package/dist/methods/port/relay-cancel.js +21 -0
  102. package/dist/methods/port/relay-cancel.js.map +1 -0
  103. package/dist/methods/port/relay-live.d.ts +25 -0
  104. package/dist/methods/port/relay-live.d.ts.map +1 -0
  105. package/dist/methods/port/relay-live.js +32 -0
  106. package/dist/methods/port/relay-live.js.map +1 -0
  107. package/dist/methods/port/relay-reconcile.d.ts +39 -0
  108. package/dist/methods/port/relay-reconcile.d.ts.map +1 -0
  109. package/dist/methods/port/relay-reconcile.js +35 -0
  110. package/dist/methods/port/relay-reconcile.js.map +1 -0
  111. package/dist/methods/port/relay-run.d.ts +47 -0
  112. package/dist/methods/port/relay-run.d.ts.map +1 -0
  113. package/dist/methods/port/relay-run.js +41 -0
  114. package/dist/methods/port/relay-run.js.map +1 -0
  115. package/dist/methods/port/submissions-deliver.d.ts +8 -0
  116. package/dist/methods/port/submissions-deliver.d.ts.map +1 -1
  117. package/dist/methods/port/submissions-deliver.js +4 -2
  118. package/dist/methods/port/submissions-deliver.js.map +1 -1
  119. package/dist/methods/relay/call-batch.d.ts +26 -0
  120. package/dist/methods/relay/call-batch.d.ts.map +1 -0
  121. package/dist/methods/relay/call-batch.js +30 -0
  122. package/dist/methods/relay/call-batch.js.map +1 -0
  123. package/dist/methods/relay/effect.d.ts +31 -0
  124. package/dist/methods/relay/effect.d.ts.map +1 -0
  125. package/dist/methods/relay/effect.js +30 -0
  126. package/dist/methods/relay/effect.js.map +1 -0
  127. package/dist/methods/relay/live-value.d.ts +33 -0
  128. package/dist/methods/relay/live-value.d.ts.map +1 -0
  129. package/dist/methods/relay/live-value.js +32 -0
  130. package/dist/methods/relay/live-value.js.map +1 -0
  131. package/dist/methods/relay/run-update.d.ts +46 -0
  132. package/dist/methods/relay/run-update.d.ts.map +1 -0
  133. package/dist/methods/relay/run-update.js +45 -0
  134. package/dist/methods/relay/run-update.js.map +1 -0
  135. package/dist/methods/remote/login-wait.d.ts +30 -0
  136. package/dist/methods/remote/login-wait.d.ts.map +1 -0
  137. package/dist/methods/remote/login-wait.js +36 -0
  138. package/dist/methods/remote/login-wait.js.map +1 -0
  139. package/dist/methods/remote/login.d.ts +41 -0
  140. package/dist/methods/remote/login.d.ts.map +1 -0
  141. package/dist/methods/remote/login.js +37 -0
  142. package/dist/methods/remote/login.js.map +1 -0
  143. package/dist/methods/remote/logout.d.ts +25 -0
  144. package/dist/methods/remote/logout.d.ts.map +1 -0
  145. package/dist/methods/remote/logout.js +28 -0
  146. package/dist/methods/remote/logout.js.map +1 -0
  147. package/dist/methods/remote/status.d.ts +14 -0
  148. package/dist/methods/remote/status.d.ts.map +1 -0
  149. package/dist/methods/remote/status.js +22 -0
  150. package/dist/methods/remote/status.js.map +1 -0
  151. package/dist/methods/remote/token.d.ts +19 -0
  152. package/dist/methods/remote/token.d.ts.map +1 -0
  153. package/dist/methods/remote/token.js +24 -0
  154. package/dist/methods/remote/token.js.map +1 -0
  155. package/dist/methods/share/start.d.ts +5 -2
  156. package/dist/methods/share/start.d.ts.map +1 -1
  157. package/dist/methods/share/start.js +6 -3
  158. package/dist/methods/share/start.js.map +1 -1
  159. package/dist/methods/state/patch.d.ts +7 -0
  160. package/dist/methods/state/patch.d.ts.map +1 -1
  161. package/dist/methods/state/patch.js +2 -1
  162. package/dist/methods/state/patch.js.map +1 -1
  163. package/dist/methods/view/url.d.ts +2 -1
  164. package/dist/methods/view/url.d.ts.map +1 -1
  165. package/dist/methods/view/url.js +2 -1
  166. package/dist/methods/view/url.js.map +1 -1
  167. package/dist/policy.d.ts +18 -0
  168. package/dist/policy.d.ts.map +1 -0
  169. package/dist/policy.js +23 -0
  170. package/dist/policy.js.map +1 -0
  171. package/dist/remote.d.ts +55 -0
  172. package/dist/remote.d.ts.map +1 -0
  173. package/dist/remote.js +52 -0
  174. package/dist/remote.js.map +1 -0
  175. package/dist/view.d.ts +1 -1
  176. package/dist/view.js +1 -1
  177. package/dist/view.js.map +1 -1
  178. package/package.json +2 -2
  179. package/schemas/protocol.draft-07.json +1607 -126
  180. package/schemas/protocol.schema.json +1543 -126
  181. package/src/actions.ts +45 -5
  182. package/src/browser.ts +6 -0
  183. package/src/capability.ts +0 -23
  184. package/src/diagnostics/codes/artifact.ts +48 -0
  185. package/src/diagnostics/codes/env.ts +12 -0
  186. package/src/diagnostics/codes/home.ts +12 -0
  187. package/src/diagnostics/codes/index.ts +6 -2
  188. package/src/diagnostics/codes/remote.ts +113 -0
  189. package/src/diagnostics/codes/submit.ts +3 -3
  190. package/src/diagnostics/diagnostic.ts +3 -1
  191. package/src/duration.ts +29 -0
  192. package/src/hygiene.ts +12 -1
  193. package/src/ids.ts +33 -1
  194. package/src/index.ts +124 -8
  195. package/src/interaction.ts +42 -2
  196. package/src/manifest.ts +115 -24
  197. package/src/methods/artifact/export.ts +68 -0
  198. package/src/methods/artifact/import.ts +39 -0
  199. package/src/methods/hosted/push.ts +146 -0
  200. package/src/methods/hosted/submission.ts +34 -0
  201. package/src/methods/index.ts +36 -0
  202. package/src/methods/instance/status.ts +4 -0
  203. package/src/methods/mostra/initialize.ts +19 -3
  204. package/src/methods/port/relay-call.ts +58 -0
  205. package/src/methods/port/relay-cancel.ts +33 -0
  206. package/src/methods/port/relay-live.ts +48 -0
  207. package/src/methods/port/relay-reconcile.ts +71 -0
  208. package/src/methods/port/relay-run.ts +80 -0
  209. package/src/methods/port/submissions-deliver.ts +13 -1
  210. package/src/methods/relay/call-batch.ts +52 -0
  211. package/src/methods/relay/effect.ts +55 -0
  212. package/src/methods/relay/live-value.ts +54 -0
  213. package/src/methods/relay/run-update.ts +81 -0
  214. package/src/methods/remote/login-wait.ts +55 -0
  215. package/src/methods/remote/login.ts +72 -0
  216. package/src/methods/remote/logout.ts +42 -0
  217. package/src/methods/remote/status.ts +34 -0
  218. package/src/methods/remote/token.ts +39 -0
  219. package/src/methods/share/start.ts +12 -4
  220. package/src/methods/state/patch.ts +6 -0
  221. package/src/methods/view/url.ts +2 -1
  222. package/src/policy.ts +30 -0
  223. package/src/remote.ts +89 -0
  224. package/src/view.ts +1 -1
package/src/actions.ts CHANGED
@@ -63,11 +63,19 @@ export const RUN_KEY_MAX = 256;
63
63
 
64
64
  /**
65
65
  * A run's state (D24, ARCHITECTURE §7). `queued`: recorded, not yet started in a worker.
66
- * `running`: started. `waiting` is reserved for a remote server's run that waits for its owner's
67
- * instance (WP-28, D117); a page that doesn't know it treats it like `queued`. The others are
68
- * final.
66
+ * `running`: started. `waiting`: a remote server's run that waits for its owner's instance (D165
67
+ * item 4); a page that doesn't know it treats it like `queued`. `unknown`: a relayed run whose
68
+ * owner never reported its end within the artifact's offline limit, which may have taken effect;
69
+ * the owner's later report replaces it once. The others are final.
69
70
  */
70
- export type RunStatus = "queued" | "running" | "waiting" | "succeeded" | "failed" | "cancelled";
71
+ export type RunStatus =
72
+ | "queued"
73
+ | "running"
74
+ | "waiting"
75
+ | "succeeded"
76
+ | "failed"
77
+ | "cancelled"
78
+ | "unknown";
71
79
 
72
80
  /** Every run status. */
73
81
  export const RUN_STATUSES: readonly RunStatus[] = [
@@ -77,6 +85,7 @@ export const RUN_STATUSES: readonly RunStatus[] = [
77
85
  "succeeded",
78
86
  "failed",
79
87
  "cancelled",
88
+ "unknown",
80
89
  ];
81
90
 
82
91
  /** Whether a run in `status` has ended. */
@@ -147,6 +156,11 @@ export interface RunState {
147
156
  readonly logFrom?: number;
148
157
  /** The index of the first batch in `batches`, as `logFrom`; absent: 0. */
149
158
  readonly batchFrom?: number;
159
+ /**
160
+ * On a remote server: the run is `running` on its owner's instance, which can't be reached now
161
+ * (D165 item 4); it ends when the owner reports, or becomes `unknown` past the offline limit.
162
+ */
163
+ readonly ownerUnreachable?: boolean;
150
164
  }
151
165
 
152
166
  /** The Zod schema of the `RunState` type. */
@@ -166,6 +180,7 @@ export const RunState: z.ZodType<RunState> = z
166
180
  joined: z.boolean().exactOptional(),
167
181
  logFrom: z.number().int().nonnegative().exactOptional(),
168
182
  batchFrom: z.number().int().nonnegative().exactOptional(),
183
+ ownerUnreachable: z.boolean().exactOptional(),
169
184
  })
170
185
  .register(wireRegistry, {
171
186
  id: "RunState",
@@ -228,6 +243,11 @@ export interface LiveState {
228
243
  * streams, whose first value may never come (WP-14's Opus review).
229
244
  */
230
245
  readonly awaiting?: boolean;
246
+ /**
247
+ * `true` on a hosted page while the artifact's owner instance is offline, so its producers
248
+ * can't refresh the value: the last value stays, with its `at` (D165 item 4).
249
+ */
250
+ readonly ownerOffline?: boolean;
231
251
  }
232
252
 
233
253
  /** One live update on the event stream: never stored as an event (D63, LL-04). */
@@ -376,6 +396,26 @@ export const RunCancelRequest: z.ZodType<RunCancelRequest> = z
376
396
  /** The keys of live sources: like JavaScript export names, which is what `live.ts` declares. */
377
397
  export const LIVE_KEY_PATTERN: RegExp = /^[A-Za-z_$][A-Za-z0-9_$]{0,127}$/;
378
398
 
399
+ /**
400
+ * The reserved live keys of tallies (D165 item 12, INTERFACES §18.4): `$tally/<field>` reads the
401
+ * count by choice of a manifest `tally` entry. No producer or push writes one (their keys follow
402
+ * {@link LIVE_KEY_PATTERN}); only a page reads them.
403
+ */
404
+ export const TALLY_LIVE_PREFIX = "$tally/";
405
+
406
+ /** The value of a tally's live key: the counts by choice, or only the total below `minTotal`. */
407
+ export interface TallyValue {
408
+ /** Each listed choice's count, absent while fewer than `minTotal` answers were counted. */
409
+ readonly counts?: Readonly<Record<string, number>>;
410
+ /** How many answers were counted: answers, never people. */
411
+ readonly total: number;
412
+ }
413
+
414
+ /** The keys a page may read: a source's ({@link LIVE_KEY_PATTERN}) or a tally's (`$tally/<field>`). */
415
+ export const READABLE_LIVE_KEY_PATTERN: RegExp =
416
+ // biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are what it refuses.
417
+ /^(?:[A-Za-z_$][A-Za-z0-9_$]{0,127}$|\$tally\/[^\u0000-\u001f\u007f]{1,256}$)/;
418
+
379
419
  /** The largest live value, in characters of serialized JSON (DATA_MODEL §5's 4 MiB). */
380
420
  export const LIVE_VALUE_MAX: number = 4 * 1024 * 1024;
381
421
 
@@ -410,7 +450,7 @@ export const LiveRequest: z.ZodType<LiveRequest> = z
410
450
  keys: z
411
451
  .array(
412
452
  z.object({
413
- key: z.string().regex(LIVE_KEY_PATTERN),
453
+ key: z.string().regex(READABLE_LIVE_KEY_PATTERN),
414
454
  window: z.int().min(1).max(LIVE_RING_MAX).exactOptional(),
415
455
  refresh: z.boolean().exactOptional(),
416
456
  }),
package/src/browser.ts CHANGED
@@ -271,6 +271,12 @@ export const FrameTicket: z.ZodType<FrameTicket> = z
271
271
  */
272
272
  export const FRAME_SESSION_HEADER = "x-mostra-frame";
273
273
 
274
+ /**
275
+ * The header a hosted shell sends its session's secret in (INTERFACES §18.4, D165 item 8): no
276
+ * cookie is ever set or read on a hosted host, so no tenant page can toss, shadow or crowd one out.
277
+ */
278
+ export const SHELL_SESSION_HEADER = "x-mostra-shell";
279
+
274
280
  /**
275
281
  * `POST /_mostra/enter` on the artifact's origin: the bootstrap page exchanges the shell's
276
282
  * single-use frame ticket, from `/_mostra/enter#t=…`, for a worker-mode frame session.
package/src/capability.ts CHANGED
@@ -44,29 +44,6 @@ export const ALL_SCOPES: readonly CapabilityScope[] = [
44
44
  "action:*",
45
45
  ];
46
46
 
47
- /**
48
- * A duration: a positive whole number and a unit, `s`, `m`, `h` or `d` (`30m`, `24h`, `7d`), as
49
- * INTERFACES §1 writes durations in flags and manifests.
50
- */
51
- export type Duration = `${number}${"s" | "m" | "h" | "d"}`;
52
-
53
- /** The Zod schema of the `Duration` type. */
54
- export const Duration: z.ZodType<Duration> = z
55
- .string()
56
- .regex(/^[1-9][0-9]{0,8}[smhd]$/)
57
- .register(wireRegistry, {
58
- id: "Duration",
59
- description: "A duration: a positive whole number and s, m, h or d, such as 30m, 24h or 7d.",
60
- }) as z.ZodType<Duration>;
61
-
62
- const UNIT_MS = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 } as const;
63
-
64
- /** The length of a `Duration` in milliseconds. */
65
- export function durationMs(duration: Duration): number {
66
- const unit = duration.slice(-1) as keyof typeof UNIT_MS;
67
- return Number(duration.slice(0, -1)) * UNIT_MS[unit];
68
- }
69
-
70
47
  /**
71
48
  * The scopes a token holds after normalization: `view` added, duplicates removed, sorted, so equal
72
49
  * grants compare equal.
@@ -15,6 +15,10 @@ export const artifactDiagnosticCodes = [
15
15
  "MOSTRA_ARTIFACT_TEMPLATE_UNKNOWN",
16
16
  "MOSTRA_ARTIFACT_VERSION_NOT_FOUND",
17
17
  "MOSTRA_ARTIFACT_VERSION_COLLECTED",
18
+ "MOSTRA_ARTIFACT_PATH_INVALID",
19
+ "MOSTRA_ARTIFACT_PATCH_REJECTED",
20
+ "MOSTRA_ARTIFACT_ID_DROPPED",
21
+ "MOSTRA_ARTIFACT_BUNDLE_INVALID",
18
22
  // gen:codes
19
23
  ] as const;
20
24
 
@@ -133,5 +137,49 @@ export const artifactDiagnostics: AreaCatalog<ArtifactDiagnosticCode> = {
133
137
  fix: "Open a version that still exists (`artifact/get` marks collected ones), or publish the exact source of this version again: publish restores its files under the same ID and number.",
134
138
  },
135
139
  },
140
+ MOSTRA_ARTIFACT_PATH_INVALID: {
141
+ severity: "error",
142
+ phase: "host",
143
+ title: "File path outside the artifact",
144
+ hint: "Name the file by a relative path inside the artifact's directory, such as `index.tsx` or `components/chart.tsx`.",
145
+ docs: {
146
+ explanation:
147
+ "`artifact_write` and `artifact_patch` change an artifact's own files, which live in its directory. A path that is absolute, climbs out with `..`, names the directory itself or passes through a link to somewhere else names no file of the artifact, so nothing is written.",
148
+ fix: "Give each file's path relative to the artifact's directory, with `/` between folders. To write elsewhere, use your own file tools.",
149
+ },
150
+ },
151
+ MOSTRA_ARTIFACT_PATCH_REJECTED: {
152
+ severity: "error",
153
+ phase: "host",
154
+ title: "Patch doesn't apply",
155
+ hint: "Read the file again and send edits whose `old` text appears in it exactly once, or a diff made against its current content.",
156
+ docs: {
157
+ explanation:
158
+ "An `artifact_patch` changes a file only when every edit applies: each `old` text must appear exactly once in the file as it is now, and each hunk of a unified diff must match its lines. When one doesn't, nothing is written, and the message lists each edit or hunk that didn't apply and why (not found, found more than once, the file is missing).",
159
+ fix: "Use a longer `old` text that appears only once, fix the hunk's context lines, or write the whole file with `artifact_write`.",
160
+ },
161
+ },
162
+ MOSTRA_ARTIFACT_ID_DROPPED: {
163
+ severity: "warning",
164
+ phase: "host",
165
+ title: "Manifest id removed",
166
+ hint: 'Put the `id: "art_…"` line back into the entry\'s `defineArtifact` (or its frontmatter), or the next publish gives the artifact a new ID.',
167
+ docs: {
168
+ explanation:
169
+ "A write replaced the artifact's entry (`index.tsx`, `index.jsx` or `index.mdx`) with text that no longer names the artifact ID its manifest held. Mostra wrote it as asked. An artifact without an `id` is bound to its source path at its first publish, so a page that was never published gets a new ID there, and one that was published keeps its ID only while its path stays the same: links, waits and results named by the old ID then don't find it.",
170
+ fix: 'Add the `id` back, exactly as it was (`id: "art_01…"` in `defineArtifact`, or `id:` in the MDX frontmatter), with `artifact_patch` or `artifact_write`.',
171
+ },
172
+ },
173
+ MOSTRA_ARTIFACT_BUNDLE_INVALID: {
174
+ severity: "error",
175
+ phase: "host",
176
+ title: "Not a bundle this version can import",
177
+ hint: "Export the bundle again with `mostra export <artifact> --as bundle`, and import the files it wrote unchanged.",
178
+ docs: {
179
+ explanation:
180
+ "Importing a bundle checks it before it keeps anything: its `mostra-bundle.json`, that its version ID is the one its artifact ID and digests give, and that its builds and source snapshot have the digests it records. This bundle failed one of those checks, so a file was changed, lost or added after it was exported, or it isn't a bundle Mostra wrote.",
181
+ fix: "Export the version again from the home that published it, and copy the bundle's directory or archive whole.",
182
+ },
183
+ },
136
184
  // gen:entries
137
185
  };
@@ -17,6 +17,7 @@ export const envDiagnosticCodes = [
17
17
  "MOSTRA_ENV_BUNDLE_UNAVAILABLE",
18
18
  "MOSTRA_ENV_NODE_UNSUPPORTED",
19
19
  "MOSTRA_ENV_HELPER_MISSING",
20
+ "MOSTRA_ENV_RUNTIME_INSTALLING",
20
21
  // gen:codes
21
22
  ] as const;
22
23
 
@@ -157,5 +158,16 @@ export const envDiagnostics: AreaCatalog<EnvDiagnosticCode> = {
157
158
  fix: "Reinstall Mostra so the runtime bundle is complete. In a development checkout, build the helper with `cargo build -p mostra-win`. A custom layout can point the runtime at the helper with `MOSTRA_WIN_HELPER`.",
158
159
  },
159
160
  },
161
+ MOSTRA_ENV_RUNTIME_INSTALLING: {
162
+ severity: "error",
163
+ phase: "host",
164
+ title: "Runtime still installing",
165
+ hint: "Call the tool again in a minute: Mostra keeps installing its runtime meanwhile.",
166
+ docs: {
167
+ explanation:
168
+ "`mostra mcp` installed from npm answers its client at once and installs its release's runtime bundle in the background on its first start (about 200 MB, D164 item 7), so a client's startup timeout never waits for the download. A tool that needs the instance waits for that install, up to 45 seconds per call; this call's time ran out first. The install goes on, and the message says how far it is. Tools that need no instance (`docs_search`, `artifact_write`, `artifact_patch`) work during it.",
169
+ fix: "Call the tool again once the install has had time to finish. When it fails instead, the next call says why (`MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED`, `MOSTRA_ENV_BUNDLE_UNAVAILABLE` offline) and starts it again.",
170
+ },
171
+ },
160
172
  // gen:entries
161
173
  };
@@ -17,6 +17,7 @@ export const homeDiagnosticCodes = [
17
17
  "MOSTRA_HOME_INTEGRITY",
18
18
  "MOSTRA_HOME_NOT_ALWAYS_ON",
19
19
  "MOSTRA_HOME_GC_INCOMPLETE",
20
+ "MOSTRA_HOME_NETWORK_FILESYSTEM",
20
21
  // gen:codes
21
22
  ] as const;
22
23
 
@@ -146,5 +147,16 @@ export const homeDiagnostics: AreaCatalog<HomeDiagnosticCode> = {
146
147
  fix: "Run `mostra gc` again; a failure that repeats names its cause in the message (for example, a file the user can't remove).",
147
148
  },
148
149
  },
150
+ MOSTRA_HOME_NETWORK_FILESYSTEM: {
151
+ severity: "error",
152
+ phase: "host",
153
+ title: "Data directory on a network filesystem",
154
+ hint: "Put the server's data directory on a local disk.",
155
+ docs: {
156
+ explanation:
157
+ "A remote server's data directory holds its hosted homes' ledgers and locks, which need a local disk: on a network filesystem a lock can seem held by two machines at once, and SQLite's WAL can't share memory across them (D165 item 0b). The server refuses a data directory it detects on NFS, SMB, AFP, WebDAV or a FUSE mount, before it opens anything.",
158
+ fix: "Pass `--data` a directory on a local disk. To keep a copy elsewhere, replicate the homes with a backup tool instead.",
159
+ },
160
+ },
149
161
  // gen:entries
150
162
  };
@@ -22,9 +22,10 @@ import { type NetworkDiagnosticCode, networkDiagnostics } from "./network.ts";
22
22
  import { type PlatformDiagnosticCode, platformDiagnostics } from "./platform.ts";
23
23
  import { type PublishDiagnosticCode, publishDiagnostics } from "./publish.ts";
24
24
  import { type RegressionDiagnosticCode, regressionDiagnostics } from "./regression.ts";
25
+ // gen:area-imports
26
+ import { type RemoteDiagnosticCode, remoteDiagnostics } from "./remote.ts";
25
27
  import { type RuntimeDiagnosticCode, runtimeDiagnostics } from "./runtime.ts";
26
28
  import { type SecretDiagnosticCode, secretDiagnostics } from "./secret.ts";
27
- // gen:area-imports
28
29
  import { type ShareDiagnosticCode, shareDiagnostics } from "./share.ts";
29
30
  import { type SmokeDiagnosticCode, smokeDiagnostics } from "./smoke.ts";
30
31
  import { type SubmitDiagnosticCode, submitDiagnostics } from "./submit.ts";
@@ -50,9 +51,10 @@ export { type NetworkDiagnosticCode, networkDiagnosticCodes } from "./network.ts
50
51
  export { type PlatformDiagnosticCode, platformDiagnosticCodes } from "./platform.ts";
51
52
  export { type PublishDiagnosticCode, publishDiagnosticCodes } from "./publish.ts";
52
53
  export { type RegressionDiagnosticCode, regressionDiagnosticCodes } from "./regression.ts";
54
+ // gen:area-exports
55
+ export { type RemoteDiagnosticCode, remoteDiagnosticCodes } from "./remote.ts";
53
56
  export { type RuntimeDiagnosticCode, runtimeDiagnosticCodes } from "./runtime.ts";
54
57
  export { type SecretDiagnosticCode, secretDiagnosticCodes } from "./secret.ts";
55
- // gen:area-exports
56
58
  export { type ShareDiagnosticCode, shareDiagnosticCodes } from "./share.ts";
57
59
  export { type SmokeDiagnosticCode, smokeDiagnosticCodes } from "./smoke.ts";
58
60
  export { type SubmitDiagnosticCode, submitDiagnosticCodes } from "./submit.ts";
@@ -63,6 +65,7 @@ export { type VerifyDiagnosticCode, verifyDiagnosticCodes } from "./verify.ts";
63
65
  /** Every code in the catalog. Codes are semver surface and are never removed (AX-03). */
64
66
  export type KnownDiagnosticCode =
65
67
  // gen:area-codes
68
+ | RemoteDiagnosticCode
66
69
  | ShareDiagnosticCode
67
70
  | CliDiagnosticCode
68
71
  | RegressionDiagnosticCode
@@ -93,6 +96,7 @@ export type KnownDiagnosticCode =
93
96
  /** Every cataloged code with its severity, phase, title, default hint and docs text. */
94
97
  export const diagnosticCatalog: Readonly<Record<KnownDiagnosticCode, DiagnosticSpec>> = {
95
98
  // gen:area-spreads
99
+ ...remoteDiagnostics,
96
100
  ...shareDiagnostics,
97
101
  ...cliDiagnostics,
98
102
  ...regressionDiagnostics,
@@ -0,0 +1,113 @@
1
+ /**
2
+ * Diagnostic codes of the REMOTE area.
3
+ */
4
+ import type { AreaCatalog } from "../spec.ts";
5
+
6
+ /** The codes of the REMOTE area, in the order they were added. */
7
+ export const remoteDiagnosticCodes = [
8
+ "MOSTRA_REMOTE_CONFIG_INVALID",
9
+ "MOSTRA_REMOTE_LOGIN_FAILED",
10
+ "MOSTRA_REMOTE_UNREACHABLE",
11
+ "MOSTRA_REMOTE_OWNER_OFFLINE",
12
+ "MOSTRA_REMOTE_QUEUE_FULL",
13
+ "MOSTRA_REMOTE_NOT_OWNER_INSTANCE",
14
+ "MOSTRA_REMOTE_SIGN_IN_REQUIRED",
15
+ "MOSTRA_REMOTE_RATE_LIMITED",
16
+ // gen:codes
17
+ ] as const;
18
+
19
+ /** The codes of the REMOTE area. */
20
+ export type RemoteDiagnosticCode = (typeof remoteDiagnosticCodes)[number];
21
+
22
+ /** The REMOTE area's catalog entries. */
23
+ export const remoteDiagnostics: AreaCatalog<RemoteDiagnosticCode> = {
24
+ MOSTRA_REMOTE_CONFIG_INVALID: {
25
+ severity: "error",
26
+ phase: "host",
27
+ title: "Remote server configuration can't be used",
28
+ hint: "Fix the configuration key the message names, then start mostra-runtime server again.",
29
+ docs: {
30
+ explanation:
31
+ "`mostra-runtime server` reads its configuration (the file `--config` names and `MOSTRA_SERVER_*` variables) before it serves anything, and stops when a key is missing, of the wrong type or out of range, naming the key. Nothing was served.",
32
+ fix: "Correct the key the message names: `apiOrigin` must be an `https:` origin (or `http:` on loopback), and `domains.active` a host name.",
33
+ },
34
+ },
35
+ MOSTRA_REMOTE_LOGIN_FAILED: {
36
+ severity: "error",
37
+ phase: "host",
38
+ title: "Signing in to a remote server failed",
39
+ hint: "Run mostra login again, and approve the code on the server's page within ten minutes.",
40
+ docs: {
41
+ explanation:
42
+ "Signing this home in to a remote server didn't finish: the code expired, the person refused it, the server refused the client, or the binding's access token was refused (revoked, expired, or for another server). Nothing of the home changed; artifacts it owns on that server stay its own.",
43
+ fix: "Sign in to the server again and approve the code on the page it names. A refusal you didn't expect means the sign-in was revoked on the server.",
44
+ },
45
+ },
46
+ MOSTRA_REMOTE_UNREACHABLE: {
47
+ severity: "error",
48
+ phase: "host",
49
+ title: "The remote server can't be reached",
50
+ hint: "Check the network and the server's address, then try again; mostra status shows the link.",
51
+ docs: {
52
+ explanation:
53
+ "The owner instance couldn't reach the remote server that holds this hosted artifact, so a write that must go there (its artifact state, a live value) was refused, never applied locally alone (D165 item 1). Nothing was lost: a page's edit stays in its journal and is sent again.",
54
+ fix: "Run `mostra status` to see each server's link. When the server is back the link reconnects by itself; then write again.",
55
+ },
56
+ },
57
+ MOSTRA_REMOTE_OWNER_OFFLINE: {
58
+ severity: "error",
59
+ phase: "host",
60
+ title: "The artifact's owner instance is offline",
61
+ hint: "Start Mostra on the machine that shared the page, or try again once it is back.",
62
+ docs: {
63
+ explanation:
64
+ "A hosted page called server code its owner instance runs, and the owner instance isn't connected. A plain call isn't kept, so it is refused at once; an action run waits or fails as the artifact's `hosted.offline` says.",
65
+ fix: 'Start Mostra on the owner\'s machine (`mostra daemon start`, or `mostra daemon install` for always-on). An action that must work while the owner is away should be an action run with `hosted.offline.actions: "queue"`.',
66
+ },
67
+ },
68
+ MOSTRA_REMOTE_QUEUE_FULL: {
69
+ severity: "error",
70
+ phase: "host",
71
+ title: "Too many runs wait for the owner",
72
+ hint: "Wait for the owner to come back and work through its queue, then press again.",
73
+ docs: {
74
+ explanation:
75
+ "The artifact's owner instance is offline and as many runs as the server allows already wait for it, so this one was refused before anything was recorded. Runs already waiting keep their place.",
76
+ fix: "Bring the owner instance back online: waiting runs then go out in the order they were made. The cap is the server's `relay.waitingRunsPerArtifact` setting.",
77
+ },
78
+ },
79
+ MOSTRA_REMOTE_NOT_OWNER_INSTANCE: {
80
+ severity: "error",
81
+ phase: "host",
82
+ title: "Another instance owns this hosted artifact",
83
+ hint: "Share or push this artifact from its owner instance, named in the message.",
84
+ docs: {
85
+ explanation:
86
+ "A hosted artifact has one owner instance: the one that shared it. It alone receives the artifact's submissions, relayed runs and authoring, and only it pushes versions of it (D165 item 1b). Another instance of the same account reads and waits through the hosted home.",
87
+ fix: "Run the command on the instance the message names. Moving an artifact to another owner instance isn't part of this release.",
88
+ },
89
+ },
90
+ MOSTRA_REMOTE_SIGN_IN_REQUIRED: {
91
+ severity: "error",
92
+ phase: "host",
93
+ title: "This action needs a signed-in viewer",
94
+ hint: "Sign in from the page's chrome, or have the owner allow this for anyone with the link.",
95
+ docs: {
96
+ explanation:
97
+ "On a hosted link, an action that runs on the owner's machine, or a submission when the artifact asks for it, needs a viewer signed in (D159, D165 item 13). Nothing was recorded.",
98
+ fix: 'Sign in with the page\'s Sign in. An owner who wants anyone with the link to run actions sets `hosted: { actions: "link" }` in the manifest (and `submissions: "link"` for answers).',
99
+ },
100
+ },
101
+ MOSTRA_REMOTE_RATE_LIMITED: {
102
+ severity: "error",
103
+ phase: "host",
104
+ title: "Too many requests on this link",
105
+ hint: "Try again after the time the answer's Retry-After gives.",
106
+ docs: {
107
+ explanation:
108
+ "Too many requests of this kind came through one link or one address in a short time, past the server's `rateLimits`. Nothing was recorded, and a draft stays as it was.",
109
+ fix: "Wait for the `Retry-After` the answer carries and try again. The limits are the server's `rateLimits` settings.",
110
+ },
111
+ },
112
+ // gen:entries
113
+ };
@@ -58,11 +58,11 @@ export const submitDiagnostics: AreaCatalog<SubmitDiagnosticCode> = {
58
58
  severity: "error",
59
59
  phase: "runtime",
60
60
  title: "No such submission",
61
- hint: "Wait for a submission with `mostra wait <artifact> --until submitted`, or name one that exists.",
61
+ hint: "Wait for a submission with `mostra wait <artifact> --until submitted`, or, when the message says the policy is none, read `mostra state get <artifact>` or wait for a signal with `--until signal:<name>`.",
62
62
  docs: {
63
63
  explanation:
64
- "The artifact has no submission yet, or none with the ID asked for. Submissions are durable once made, so this means none was made (or the ID belongs to another artifact or home).",
65
- fix: "Run `mostra wait <artifact> --until submitted` to block until the viewer submits, then read the results. List the artifact's submissions through `submission.created` events.",
64
+ "The artifact has no submission yet, or none with the ID asked for. Submissions are durable once made, so this means none was made (or the ID belongs to another artifact or home). An artifact whose submission policy is `none` never has one, and the message says so: its viewers' work is in its shared state, its signals and its action runs.",
65
+ fix: "Run `mostra wait <artifact> --until submitted` to block until the viewer submits, then read the results. List the artifact's submissions through `submission.created` events. Under policy `none`, read the shared state with `mostra state get <artifact>`, or wait for a signal the page raises with `mostra wait <artifact> --until signal:<name>`: its event carries the signal's payload.",
66
66
  },
67
67
  },
68
68
  MOSTRA_SUBMIT_VIEW_INVALID: {
@@ -39,7 +39,8 @@ export type DiagnosticArea =
39
39
  | "ENV"
40
40
  | "PLATFORM"
41
41
  | "ARTIFACT"
42
- | "CLI";
42
+ | "CLI"
43
+ | "REMOTE";
43
44
 
44
45
  /** Every diagnostic area, in INTERFACES §13 order. */
45
46
  export const DIAGNOSTIC_AREAS: readonly DiagnosticArea[] = [
@@ -73,6 +74,7 @@ export const DIAGNOSTIC_AREAS: readonly DiagnosticArea[] = [
73
74
  "PLATFORM",
74
75
  "ARTIFACT",
75
76
  "CLI",
77
+ "REMOTE",
76
78
  ];
77
79
 
78
80
  /**
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Durations as INTERFACES §1 writes them in flags and manifests: a module of its own, so the
3
+ * manifest and capability links share it without either pulling the other into a browser bundle.
4
+ */
5
+ import * as z from "zod";
6
+ import { wireRegistry } from "./wire-registry.ts";
7
+
8
+ /**
9
+ * A duration: a positive whole number and a unit, `s`, `m`, `h` or `d` (`30m`, `24h`, `7d`), as
10
+ * INTERFACES §1 writes durations in flags and manifests.
11
+ */
12
+ export type Duration = `${number}${"s" | "m" | "h" | "d"}`;
13
+
14
+ /** The Zod schema of the `Duration` type. */
15
+ export const Duration: z.ZodType<Duration> = z
16
+ .string()
17
+ .regex(/^[1-9][0-9]{0,8}[smhd]$/)
18
+ .register(wireRegistry, {
19
+ id: "Duration",
20
+ description: "A duration: a positive whole number and s, m, h or d, such as 30m, 24h or 7d.",
21
+ }) as z.ZodType<Duration>;
22
+
23
+ const UNIT_MS = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 } as const;
24
+
25
+ /** The length of a `Duration` in milliseconds. */
26
+ export function durationMs(duration: Duration): number {
27
+ const unit = duration.slice(-1) as keyof typeof UNIT_MS;
28
+ return Number(duration.slice(0, -1)) * UNIT_MS[unit];
29
+ }
package/src/hygiene.ts CHANGED
@@ -34,8 +34,11 @@ export interface RequestPolicy {
34
34
  * `Origin` and a JSON content type, but no CSRF token yet.
35
35
  * - `mutation`: any other state change: `Origin`, a JSON content type and the session's CSRF
36
36
  * token in `X-Mostra-CSRF`.
37
+ * - `rpc`: a JSON-RPC POST from a program that holds a bearer token (`mostra mcp --http`, D164): a
38
+ * foreign `Origin` is refused and none is fine, since browsers send one on every POST; a JSON
39
+ * content type. The endpoint checks the token itself, as it checks a session.
37
40
  */
38
- export type RequestIntent = "read" | "stream" | "upgrade" | "exchange" | "mutation";
41
+ export type RequestIntent = "read" | "stream" | "upgrade" | "exchange" | "mutation" | "rpc";
39
42
 
40
43
  /** One request as the transport received it. */
41
44
  export interface RequestFacts {
@@ -187,6 +190,14 @@ export function checkRequest(policy: RequestPolicy, request: RequestFacts): Refu
187
190
  return refusal("MOSTRA_HYGIENE_ORIGIN_REFUSED", "The request came from another origin.");
188
191
  }
189
192
  return undefined;
193
+ case "rpc":
194
+ if (origin !== undefined && origin !== policy.origin) {
195
+ return refusal("MOSTRA_HYGIENE_ORIGIN_REFUSED", "The request came from another origin.");
196
+ }
197
+ if (!isJsonContentType(headerValue(request.headers, "content-type"))) {
198
+ return refusal("MOSTRA_HYGIENE_CONTENT_TYPE", "The request's body isn't declared as JSON.");
199
+ }
200
+ return undefined;
190
201
  case "stream": {
191
202
  const site = headerValue(request.headers, "sec-fetch-site");
192
203
  const sameOrigin = origin === undefined ? site === "same-origin" : origin === policy.origin;
package/src/ids.ts CHANGED
@@ -29,7 +29,11 @@ export type IdPrefix =
29
29
  | "cmt"
30
30
  | "tok"
31
31
  | "mut"
32
- | "shr";
32
+ | "shr"
33
+ | "acct"
34
+ | "hom"
35
+ | "lnk"
36
+ | "rte";
33
37
 
34
38
  /**
35
39
  * A branded ID string. The brand exists only at the type level, so an `Id<"art">` is a plain
@@ -250,6 +254,34 @@ export const ShareId: GeneratedIdKind<"shr"> = generated(
250
254
  defineKind("shr", "share", "ulid", "ShareId"),
251
255
  );
252
256
 
257
+ /** An account on a remote server (`acct_` + ULID, D165 item 8). */
258
+ export type AccountId = Id<"acct">;
259
+ /** Account IDs. */
260
+ export const AccountId: GeneratedIdKind<"acct"> = generated(
261
+ defineKind("acct", "account", "ulid", "AccountId"),
262
+ );
263
+
264
+ /** A hosted home on a remote server (`hom_` + ULID, D165 item 1). */
265
+ export type HomeId = Id<"hom">;
266
+ /** Hosted home IDs. */
267
+ export const HomeId: GeneratedIdKind<"hom"> = generated(
268
+ defineKind("hom", "hosted home", "ulid", "HomeId"),
269
+ );
270
+
271
+ /** An instance linked to a remote server (`lnk_` + ULID, D165 item 2): its owner link. */
272
+ export type LinkId = Id<"lnk">;
273
+ /** Instance link IDs. */
274
+ export const LinkId: GeneratedIdKind<"lnk"> = generated(
275
+ defineKind("lnk", "instance link", "ulid", "LinkId"),
276
+ );
277
+
278
+ /** A hosted route (`rte_` + ULID): one artifact on one hosted home (D165, after the Opus review). */
279
+ export type RouteId = Id<"rte">;
280
+ /** Hosted route IDs. */
281
+ export const RouteId: GeneratedIdKind<"rte"> = generated(
282
+ defineKind("rte", "hosted route", "ulid", "RouteId"),
283
+ );
284
+
253
285
  /**
254
286
  * An event cursor: the decimal string of a home-wide event position (INTERFACES §1). Decimal
255
287
  * strings keep 64-bit positions exact in JavaScript.