@mostra/protocol 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 (211) 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 +12 -1
  20. package/dist/diagnostics/codes/artifact.js.map +1 -1
  21. package/dist/diagnostics/codes/home.d.ts +1 -1
  22. package/dist/diagnostics/codes/home.d.ts.map +1 -1
  23. package/dist/diagnostics/codes/home.js +12 -1
  24. package/dist/diagnostics/codes/home.js.map +1 -1
  25. package/dist/diagnostics/codes/index.d.ts +3 -2
  26. package/dist/diagnostics/codes/index.d.ts.map +1 -1
  27. package/dist/diagnostics/codes/index.js +3 -1
  28. package/dist/diagnostics/codes/index.js.map +1 -1
  29. package/dist/diagnostics/codes/remote.d.ts +8 -0
  30. package/dist/diagnostics/codes/remote.d.ts.map +1 -0
  31. package/dist/diagnostics/codes/remote.js +99 -0
  32. package/dist/diagnostics/codes/remote.js.map +1 -0
  33. package/dist/diagnostics/diagnostic.d.ts +1 -1
  34. package/dist/diagnostics/diagnostic.d.ts.map +1 -1
  35. package/dist/diagnostics/diagnostic.js +2 -1
  36. package/dist/diagnostics/diagnostic.js.map +1 -1
  37. package/dist/duration.d.ts +13 -0
  38. package/dist/duration.d.ts.map +1 -0
  39. package/dist/duration.js +27 -0
  40. package/dist/duration.js.map +1 -0
  41. package/dist/ids.d.ts +17 -1
  42. package/dist/ids.d.ts.map +1 -1
  43. package/dist/ids.js +9 -1
  44. package/dist/ids.js.map +1 -1
  45. package/dist/index.d.ts +30 -8
  46. package/dist/index.js +30 -8
  47. package/dist/interaction.d.ts +28 -2
  48. package/dist/interaction.d.ts.map +1 -1
  49. package/dist/interaction.js +20 -5
  50. package/dist/interaction.js.map +1 -1
  51. package/dist/manifest.d.ts +59 -14
  52. package/dist/manifest.d.ts.map +1 -1
  53. package/dist/manifest.js +63 -15
  54. package/dist/manifest.js.map +1 -1
  55. package/dist/methods/artifact/export.d.ts +40 -0
  56. package/dist/methods/artifact/export.d.ts.map +1 -0
  57. package/dist/methods/artifact/export.js +36 -0
  58. package/dist/methods/artifact/export.js.map +1 -0
  59. package/dist/methods/artifact/import.d.ts +23 -0
  60. package/dist/methods/artifact/import.d.ts.map +1 -0
  61. package/dist/methods/artifact/import.js +25 -0
  62. package/dist/methods/artifact/import.js.map +1 -0
  63. package/dist/methods/artifact/publish.d.ts +2 -1
  64. package/dist/methods/artifact/publish.d.ts.map +1 -1
  65. package/dist/methods/artifact/publish.js +1 -1
  66. package/dist/methods/hosted/push.d.ts +76 -0
  67. package/dist/methods/hosted/push.d.ts.map +1 -0
  68. package/dist/methods/hosted/push.js +71 -0
  69. package/dist/methods/hosted/push.js.map +1 -0
  70. package/dist/methods/hosted/submission.d.ts +18 -0
  71. package/dist/methods/hosted/submission.d.ts.map +1 -0
  72. package/dist/methods/hosted/submission.js +23 -0
  73. package/dist/methods/hosted/submission.js.map +1 -0
  74. package/dist/methods/index.d.ts.map +1 -1
  75. package/dist/methods/index.js +38 -2
  76. package/dist/methods/index.js.map +1 -1
  77. package/dist/methods/instance/status.d.ts +3 -0
  78. package/dist/methods/instance/status.d.ts.map +1 -1
  79. package/dist/methods/instance/status.js +3 -1
  80. package/dist/methods/instance/status.js.map +1 -1
  81. package/dist/methods/mostra/initialize.d.ts +17 -3
  82. package/dist/methods/mostra/initialize.d.ts.map +1 -1
  83. package/dist/methods/mostra/initialize.js +11 -3
  84. package/dist/methods/mostra/initialize.js.map +1 -1
  85. package/dist/methods/port/relay-call.d.ts +33 -0
  86. package/dist/methods/port/relay-call.d.ts.map +1 -0
  87. package/dist/methods/port/relay-call.js +31 -0
  88. package/dist/methods/port/relay-call.js.map +1 -0
  89. package/dist/methods/port/relay-cancel.d.ts +16 -0
  90. package/dist/methods/port/relay-cancel.d.ts.map +1 -0
  91. package/dist/methods/port/relay-cancel.js +21 -0
  92. package/dist/methods/port/relay-cancel.js.map +1 -0
  93. package/dist/methods/port/relay-live.d.ts +25 -0
  94. package/dist/methods/port/relay-live.d.ts.map +1 -0
  95. package/dist/methods/port/relay-live.js +32 -0
  96. package/dist/methods/port/relay-live.js.map +1 -0
  97. package/dist/methods/port/relay-reconcile.d.ts +39 -0
  98. package/dist/methods/port/relay-reconcile.d.ts.map +1 -0
  99. package/dist/methods/port/relay-reconcile.js +35 -0
  100. package/dist/methods/port/relay-reconcile.js.map +1 -0
  101. package/dist/methods/port/relay-run.d.ts +47 -0
  102. package/dist/methods/port/relay-run.d.ts.map +1 -0
  103. package/dist/methods/port/relay-run.js +41 -0
  104. package/dist/methods/port/relay-run.js.map +1 -0
  105. package/dist/methods/port/submissions-deliver.d.ts +8 -0
  106. package/dist/methods/port/submissions-deliver.d.ts.map +1 -1
  107. package/dist/methods/port/submissions-deliver.js +4 -2
  108. package/dist/methods/port/submissions-deliver.js.map +1 -1
  109. package/dist/methods/relay/call-batch.d.ts +26 -0
  110. package/dist/methods/relay/call-batch.d.ts.map +1 -0
  111. package/dist/methods/relay/call-batch.js +30 -0
  112. package/dist/methods/relay/call-batch.js.map +1 -0
  113. package/dist/methods/relay/effect.d.ts +31 -0
  114. package/dist/methods/relay/effect.d.ts.map +1 -0
  115. package/dist/methods/relay/effect.js +30 -0
  116. package/dist/methods/relay/effect.js.map +1 -0
  117. package/dist/methods/relay/live-value.d.ts +33 -0
  118. package/dist/methods/relay/live-value.d.ts.map +1 -0
  119. package/dist/methods/relay/live-value.js +32 -0
  120. package/dist/methods/relay/live-value.js.map +1 -0
  121. package/dist/methods/relay/run-update.d.ts +46 -0
  122. package/dist/methods/relay/run-update.d.ts.map +1 -0
  123. package/dist/methods/relay/run-update.js +45 -0
  124. package/dist/methods/relay/run-update.js.map +1 -0
  125. package/dist/methods/remote/login-wait.d.ts +30 -0
  126. package/dist/methods/remote/login-wait.d.ts.map +1 -0
  127. package/dist/methods/remote/login-wait.js +36 -0
  128. package/dist/methods/remote/login-wait.js.map +1 -0
  129. package/dist/methods/remote/login.d.ts +41 -0
  130. package/dist/methods/remote/login.d.ts.map +1 -0
  131. package/dist/methods/remote/login.js +37 -0
  132. package/dist/methods/remote/login.js.map +1 -0
  133. package/dist/methods/remote/logout.d.ts +25 -0
  134. package/dist/methods/remote/logout.d.ts.map +1 -0
  135. package/dist/methods/remote/logout.js +28 -0
  136. package/dist/methods/remote/logout.js.map +1 -0
  137. package/dist/methods/remote/status.d.ts +14 -0
  138. package/dist/methods/remote/status.d.ts.map +1 -0
  139. package/dist/methods/remote/status.js +22 -0
  140. package/dist/methods/remote/status.js.map +1 -0
  141. package/dist/methods/remote/token.d.ts +19 -0
  142. package/dist/methods/remote/token.d.ts.map +1 -0
  143. package/dist/methods/remote/token.js +24 -0
  144. package/dist/methods/remote/token.js.map +1 -0
  145. package/dist/methods/share/start.d.ts +5 -2
  146. package/dist/methods/share/start.d.ts.map +1 -1
  147. package/dist/methods/share/start.js +6 -3
  148. package/dist/methods/share/start.js.map +1 -1
  149. package/dist/methods/state/patch.d.ts +7 -0
  150. package/dist/methods/state/patch.d.ts.map +1 -1
  151. package/dist/methods/state/patch.js +2 -1
  152. package/dist/methods/state/patch.js.map +1 -1
  153. package/dist/methods/view/url.d.ts +2 -1
  154. package/dist/methods/view/url.d.ts.map +1 -1
  155. package/dist/methods/view/url.js +2 -1
  156. package/dist/methods/view/url.js.map +1 -1
  157. package/dist/policy.d.ts +18 -0
  158. package/dist/policy.d.ts.map +1 -0
  159. package/dist/policy.js +23 -0
  160. package/dist/policy.js.map +1 -0
  161. package/dist/remote.d.ts +55 -0
  162. package/dist/remote.d.ts.map +1 -0
  163. package/dist/remote.js +52 -0
  164. package/dist/remote.js.map +1 -0
  165. package/dist/view.d.ts +1 -1
  166. package/dist/view.js +1 -1
  167. package/dist/view.js.map +1 -1
  168. package/package.json +2 -2
  169. package/schemas/protocol.draft-07.json +1607 -126
  170. package/schemas/protocol.schema.json +1543 -126
  171. package/src/actions.ts +45 -5
  172. package/src/browser.ts +6 -0
  173. package/src/capability.ts +0 -23
  174. package/src/diagnostics/codes/artifact.ts +12 -0
  175. package/src/diagnostics/codes/home.ts +12 -0
  176. package/src/diagnostics/codes/index.ts +6 -2
  177. package/src/diagnostics/codes/remote.ts +113 -0
  178. package/src/diagnostics/diagnostic.ts +3 -1
  179. package/src/duration.ts +29 -0
  180. package/src/ids.ts +33 -1
  181. package/src/index.ts +124 -8
  182. package/src/interaction.ts +42 -2
  183. package/src/manifest.ts +115 -24
  184. package/src/methods/artifact/export.ts +68 -0
  185. package/src/methods/artifact/import.ts +39 -0
  186. package/src/methods/hosted/push.ts +146 -0
  187. package/src/methods/hosted/submission.ts +34 -0
  188. package/src/methods/index.ts +36 -0
  189. package/src/methods/instance/status.ts +4 -0
  190. package/src/methods/mostra/initialize.ts +19 -3
  191. package/src/methods/port/relay-call.ts +58 -0
  192. package/src/methods/port/relay-cancel.ts +33 -0
  193. package/src/methods/port/relay-live.ts +48 -0
  194. package/src/methods/port/relay-reconcile.ts +71 -0
  195. package/src/methods/port/relay-run.ts +80 -0
  196. package/src/methods/port/submissions-deliver.ts +13 -1
  197. package/src/methods/relay/call-batch.ts +52 -0
  198. package/src/methods/relay/effect.ts +55 -0
  199. package/src/methods/relay/live-value.ts +54 -0
  200. package/src/methods/relay/run-update.ts +81 -0
  201. package/src/methods/remote/login-wait.ts +55 -0
  202. package/src/methods/remote/login.ts +72 -0
  203. package/src/methods/remote/logout.ts +42 -0
  204. package/src/methods/remote/status.ts +34 -0
  205. package/src/methods/remote/token.ts +39 -0
  206. package/src/methods/share/start.ts +12 -4
  207. package/src/methods/state/patch.ts +6 -0
  208. package/src/methods/view/url.ts +2 -1
  209. package/src/policy.ts +30 -0
  210. package/src/remote.ts +89 -0
  211. 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.
@@ -18,6 +18,7 @@ export const artifactDiagnosticCodes = [
18
18
  "MOSTRA_ARTIFACT_PATH_INVALID",
19
19
  "MOSTRA_ARTIFACT_PATCH_REJECTED",
20
20
  "MOSTRA_ARTIFACT_ID_DROPPED",
21
+ "MOSTRA_ARTIFACT_BUNDLE_INVALID",
21
22
  // gen:codes
22
23
  ] as const;
23
24
 
@@ -169,5 +170,16 @@ export const artifactDiagnostics: AreaCatalog<ArtifactDiagnosticCode> = {
169
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`.',
170
171
  },
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
+ },
172
184
  // gen:entries
173
185
  };
@@ -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
+ };
@@ -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/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.