@mostra/runtime 0.10.0 → 0.12.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 (257) hide show
  1. package/dist/bin.js +4178 -310
  2. package/dist/bin.js.map +1 -1
  3. package/dist/index.d.ts.map +1 -1
  4. package/dist/index.js +1 -1
  5. package/dist/{instance-FExcyENK.js → instance-CBUlOmzG.js} +1892 -85
  6. package/dist/instance-CBUlOmzG.js.map +1 -0
  7. package/dist/reference/cli.md +1432 -0
  8. package/dist/reference/diagnostics.json +1579 -0
  9. package/dist/reference/errors/MOSTRA_A11Y_MINOR.md +23 -0
  10. package/dist/reference/errors/MOSTRA_A11Y_SERIOUS.md +23 -0
  11. package/dist/reference/errors/MOSTRA_ACTION_CANCELLED.md +23 -0
  12. package/dist/reference/errors/MOSTRA_ACTION_EVENT_INVALID.md +23 -0
  13. package/dist/reference/errors/MOSTRA_ACTION_EXPORT_INVALID.md +23 -0
  14. package/dist/reference/errors/MOSTRA_ACTION_INTERRUPTED.md +23 -0
  15. package/dist/reference/errors/MOSTRA_ACTION_PAUSED.md +23 -0
  16. package/dist/reference/errors/MOSTRA_ACTION_RUN_NOT_FOUND.md +23 -0
  17. package/dist/reference/errors/MOSTRA_ACTION_THREW.md +23 -0
  18. package/dist/reference/errors/MOSTRA_ACTION_TOO_LARGE.md +23 -0
  19. package/dist/reference/errors/MOSTRA_ACTION_UNKNOWN_FUNCTION.md +23 -0
  20. package/dist/reference/errors/MOSTRA_ACTION_UNSERIALIZABLE.md +23 -0
  21. package/dist/reference/errors/MOSTRA_ARTIFACT_BUNDLE_INVALID.md +23 -0
  22. package/dist/reference/errors/MOSTRA_ARTIFACT_DIR_NOT_EMPTY.md +23 -0
  23. package/dist/reference/errors/MOSTRA_ARTIFACT_ENTRY_AMBIGUOUS.md +23 -0
  24. package/dist/reference/errors/MOSTRA_ARTIFACT_ID_DROPPED.md +23 -0
  25. package/dist/reference/errors/MOSTRA_ARTIFACT_NOT_FOUND.md +23 -0
  26. package/dist/reference/errors/MOSTRA_ARTIFACT_NO_ENTRY.md +23 -0
  27. package/dist/reference/errors/MOSTRA_ARTIFACT_NO_PAGE.md +23 -0
  28. package/dist/reference/errors/MOSTRA_ARTIFACT_PATCH_REJECTED.md +23 -0
  29. package/dist/reference/errors/MOSTRA_ARTIFACT_PATH_INVALID.md +23 -0
  30. package/dist/reference/errors/MOSTRA_ARTIFACT_SOURCE_MISSING.md +23 -0
  31. package/dist/reference/errors/MOSTRA_ARTIFACT_SOURCE_UNREADABLE.md +23 -0
  32. package/dist/reference/errors/MOSTRA_ARTIFACT_TEMPLATE_UNKNOWN.md +23 -0
  33. package/dist/reference/errors/MOSTRA_ARTIFACT_VERSION_COLLECTED.md +23 -0
  34. package/dist/reference/errors/MOSTRA_ARTIFACT_VERSION_NOT_FOUND.md +23 -0
  35. package/dist/reference/errors/MOSTRA_BUILD_CRASHED.md +23 -0
  36. package/dist/reference/errors/MOSTRA_BUILD_FAILED.md +23 -0
  37. package/dist/reference/errors/MOSTRA_BUILD_TIMEOUT.md +23 -0
  38. package/dist/reference/errors/MOSTRA_BUILD_UNRESOLVED.md +23 -0
  39. package/dist/reference/errors/MOSTRA_CLI_CONFIG_UNWRITABLE.md +23 -0
  40. package/dist/reference/errors/MOSTRA_CLI_UNKNOWN_COMMAND.md +23 -0
  41. package/dist/reference/errors/MOSTRA_CLI_USAGE.md +23 -0
  42. package/dist/reference/errors/MOSTRA_CONSOLE_ERROR.md +23 -0
  43. package/dist/reference/errors/MOSTRA_CONSOLE_WARNING.md +23 -0
  44. package/dist/reference/errors/MOSTRA_DEP_INSTALL_FAILED.md +23 -0
  45. package/dist/reference/errors/MOSTRA_DEP_MISSING.md +23 -0
  46. package/dist/reference/errors/MOSTRA_DEP_NOT_FOUND.md +23 -0
  47. package/dist/reference/errors/MOSTRA_DEP_OFFLINE.md +23 -0
  48. package/dist/reference/errors/MOSTRA_DEP_SPEC_INVALID.md +23 -0
  49. package/dist/reference/errors/MOSTRA_DEP_TIMEOUT.md +23 -0
  50. package/dist/reference/errors/MOSTRA_DEP_WARM_CONFLICT.md +23 -0
  51. package/dist/reference/errors/MOSTRA_ENV_BIND_FAILED.md +23 -0
  52. package/dist/reference/errors/MOSTRA_ENV_BROWSER_MISSING.md +23 -0
  53. package/dist/reference/errors/MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED.md +23 -0
  54. package/dist/reference/errors/MOSTRA_ENV_BUNDLE_INVALID.md +23 -0
  55. package/dist/reference/errors/MOSTRA_ENV_BUNDLE_UNAVAILABLE.md +23 -0
  56. package/dist/reference/errors/MOSTRA_ENV_HELPER_MISSING.md +23 -0
  57. package/dist/reference/errors/MOSTRA_ENV_NODE_UNSUPPORTED.md +23 -0
  58. package/dist/reference/errors/MOSTRA_ENV_PORT_TAKEN.md +23 -0
  59. package/dist/reference/errors/MOSTRA_ENV_RUNTIME_INSTALLING.md +23 -0
  60. package/dist/reference/errors/MOSTRA_ENV_RUNTIME_MISSING.md +23 -0
  61. package/dist/reference/errors/MOSTRA_ENV_SERVICE_FAILED.md +23 -0
  62. package/dist/reference/errors/MOSTRA_ENV_SHELL_MISSING.md +23 -0
  63. package/dist/reference/errors/MOSTRA_ENV_WARM_MISSING.md +23 -0
  64. package/dist/reference/errors/MOSTRA_FIELD_CONFLICT.md +23 -0
  65. package/dist/reference/errors/MOSTRA_FIELD_DUPLICATE_ID.md +23 -0
  66. package/dist/reference/errors/MOSTRA_FIELD_ID_INVALID.md +23 -0
  67. package/dist/reference/errors/MOSTRA_FIELD_ID_UNSTABLE.md +23 -0
  68. package/dist/reference/errors/MOSTRA_FIELD_MUTATION_ID_REUSED.md +23 -0
  69. package/dist/reference/errors/MOSTRA_FIELD_SHARED.md +23 -0
  70. package/dist/reference/errors/MOSTRA_FIELD_TOO_LARGE.md +23 -0
  71. package/dist/reference/errors/MOSTRA_FIELD_UNBOUND.md +23 -0
  72. package/dist/reference/errors/MOSTRA_HOME_DISK_FULL.md +23 -0
  73. package/dist/reference/errors/MOSTRA_HOME_GC_INCOMPLETE.md +23 -0
  74. package/dist/reference/errors/MOSTRA_HOME_GONE.md +23 -0
  75. package/dist/reference/errors/MOSTRA_HOME_INTEGRITY.md +23 -0
  76. package/dist/reference/errors/MOSTRA_HOME_LEDGER_UNREADABLE.md +23 -0
  77. package/dist/reference/errors/MOSTRA_HOME_LOCKED.md +23 -0
  78. package/dist/reference/errors/MOSTRA_HOME_MISMATCH.md +23 -0
  79. package/dist/reference/errors/MOSTRA_HOME_NETWORK_FILESYSTEM.md +23 -0
  80. package/dist/reference/errors/MOSTRA_HOME_NOT_ALWAYS_ON.md +23 -0
  81. package/dist/reference/errors/MOSTRA_HOME_NOT_OWNED.md +23 -0
  82. package/dist/reference/errors/MOSTRA_HOME_SOCKET_TOO_LONG.md +23 -0
  83. package/dist/reference/errors/MOSTRA_HOME_TOO_NEW.md +23 -0
  84. package/dist/reference/errors/MOSTRA_HOST_CONNECTION_CLOSED.md +23 -0
  85. package/dist/reference/errors/MOSTRA_HOST_CURSOR_COMPACTED.md +23 -0
  86. package/dist/reference/errors/MOSTRA_HOST_IDENTITY_UNAVAILABLE.md +23 -0
  87. package/dist/reference/errors/MOSTRA_HOST_INITIALIZE_ORDER.md +23 -0
  88. package/dist/reference/errors/MOSTRA_HOST_INTERNAL_ERROR.md +23 -0
  89. package/dist/reference/errors/MOSTRA_HOST_INVALID_PARAMS.md +23 -0
  90. package/dist/reference/errors/MOSTRA_HOST_MALFORMED.md +23 -0
  91. package/dist/reference/errors/MOSTRA_HOST_MESSAGE_TOO_LARGE.md +23 -0
  92. package/dist/reference/errors/MOSTRA_HOST_METHOD_UNKNOWN.md +23 -0
  93. package/dist/reference/errors/MOSTRA_HOST_NOTIFICATION_UNSUPPORTED.md +23 -0
  94. package/dist/reference/errors/MOSTRA_HOST_PORT_UNSUPPORTED.md +23 -0
  95. package/dist/reference/errors/MOSTRA_HOST_REQUEST_ID_REUSED.md +23 -0
  96. package/dist/reference/errors/MOSTRA_HOST_REVISION_UNSUPPORTED.md +23 -0
  97. package/dist/reference/errors/MOSTRA_HOST_SHUTDOWN_REFUSED.md +23 -0
  98. package/dist/reference/errors/MOSTRA_HOST_SUBSCRIPTION_UNKNOWN.md +23 -0
  99. package/dist/reference/errors/MOSTRA_HOST_TIMEOUT.md +23 -0
  100. package/dist/reference/errors/MOSTRA_HYGIENE_CONTENT_TYPE.md +23 -0
  101. package/dist/reference/errors/MOSTRA_HYGIENE_CSRF_MISSING.md +23 -0
  102. package/dist/reference/errors/MOSTRA_HYGIENE_FRAME_SESSION.md +23 -0
  103. package/dist/reference/errors/MOSTRA_HYGIENE_HEADERS_TOO_LARGE.md +23 -0
  104. package/dist/reference/errors/MOSTRA_HYGIENE_HOST_REFUSED.md +23 -0
  105. package/dist/reference/errors/MOSTRA_HYGIENE_NOT_SERVED.md +23 -0
  106. package/dist/reference/errors/MOSTRA_HYGIENE_ORIGIN_REFUSED.md +23 -0
  107. package/dist/reference/errors/MOSTRA_HYGIENE_RATE_LIMITED.md +23 -0
  108. package/dist/reference/errors/MOSTRA_HYGIENE_REQUEST_MALFORMED.md +23 -0
  109. package/dist/reference/errors/MOSTRA_HYGIENE_SCOPE_DENIED.md +23 -0
  110. package/dist/reference/errors/MOSTRA_HYGIENE_SESSION_CONFLICT.md +23 -0
  111. package/dist/reference/errors/MOSTRA_HYGIENE_SESSION_MISSING.md +23 -0
  112. package/dist/reference/errors/MOSTRA_HYGIENE_TOKEN_INVALID.md +23 -0
  113. package/dist/reference/errors/MOSTRA_HYGIENE_TOKEN_REVOKED.md +23 -0
  114. package/dist/reference/errors/MOSTRA_LIVE_SOURCE_FAILED.md +23 -0
  115. package/dist/reference/errors/MOSTRA_LIVE_TOO_LARGE.md +23 -0
  116. package/dist/reference/errors/MOSTRA_MANIFEST_INVALID.md +23 -0
  117. package/dist/reference/errors/MOSTRA_MANIFEST_NOT_LITERAL.md +23 -0
  118. package/dist/reference/errors/MOSTRA_MANIFEST_UNKNOWN_KEY.md +23 -0
  119. package/dist/reference/errors/MOSTRA_NETWORK_EXTERNAL_FAILED.md +23 -0
  120. package/dist/reference/errors/MOSTRA_NETWORK_REQUEST_FAILED.md +23 -0
  121. package/dist/reference/errors/MOSTRA_PLATFORM_UNSUPPORTED.md +23 -0
  122. package/dist/reference/errors/MOSTRA_PUBLISH_ID_CONFLICT.md +23 -0
  123. package/dist/reference/errors/MOSTRA_PUBLISH_SOURCE_CHANGED.md +23 -0
  124. package/dist/reference/errors/MOSTRA_PUBLISH_VERIFY_FAILED.md +23 -0
  125. package/dist/reference/errors/MOSTRA_REGRESSION_ACTION_REMOVED.md +23 -0
  126. package/dist/reference/errors/MOSTRA_REGRESSION_ARIA.md +23 -0
  127. package/dist/reference/errors/MOSTRA_REGRESSION_FIELD_REMOVED.md +23 -0
  128. package/dist/reference/errors/MOSTRA_REGRESSION_LIVE_REMOVED.md +23 -0
  129. package/dist/reference/errors/MOSTRA_REGRESSION_PAGE_REMOVED.md +23 -0
  130. package/dist/reference/errors/MOSTRA_REGRESSION_PIXELS.md +23 -0
  131. package/dist/reference/errors/MOSTRA_REMOTE_CONFIG_INVALID.md +23 -0
  132. package/dist/reference/errors/MOSTRA_REMOTE_HOME_MOVING.md +23 -0
  133. package/dist/reference/errors/MOSTRA_REMOTE_HOME_SUSPENDED.md +23 -0
  134. package/dist/reference/errors/MOSTRA_REMOTE_LIMIT_REACHED.md +23 -0
  135. package/dist/reference/errors/MOSTRA_REMOTE_LOGIN_FAILED.md +23 -0
  136. package/dist/reference/errors/MOSTRA_REMOTE_NOT_OWNER_INSTANCE.md +23 -0
  137. package/dist/reference/errors/MOSTRA_REMOTE_NO_INSTANCE.md +23 -0
  138. package/dist/reference/errors/MOSTRA_REMOTE_OPERATOR_UNAVAILABLE.md +23 -0
  139. package/dist/reference/errors/MOSTRA_REMOTE_OWNER_OFFLINE.md +23 -0
  140. package/dist/reference/errors/MOSTRA_REMOTE_PAUSED_BY_OPERATOR.md +23 -0
  141. package/dist/reference/errors/MOSTRA_REMOTE_QUEUE_FULL.md +23 -0
  142. package/dist/reference/errors/MOSTRA_REMOTE_RATE_LIMITED.md +23 -0
  143. package/dist/reference/errors/MOSTRA_REMOTE_SIGN_IN_REQUIRED.md +23 -0
  144. package/dist/reference/errors/MOSTRA_REMOTE_UNDER_REVIEW.md +23 -0
  145. package/dist/reference/errors/MOSTRA_REMOTE_UNREACHABLE.md +23 -0
  146. package/dist/reference/errors/MOSTRA_RUNTIME_BLANK.md +23 -0
  147. package/dist/reference/errors/MOSTRA_RUNTIME_NOT_READY.md +23 -0
  148. package/dist/reference/errors/MOSTRA_RUNTIME_PAGE_ERROR.md +23 -0
  149. package/dist/reference/errors/MOSTRA_RUNTIME_WORKER_CRASHED.md +23 -0
  150. package/dist/reference/errors/MOSTRA_RUNTIME_WORKER_PARKED.md +23 -0
  151. package/dist/reference/errors/MOSTRA_SECRET_MISSING.md +23 -0
  152. package/dist/reference/errors/MOSTRA_SHARE_NOT_ENABLED.md +23 -0
  153. package/dist/reference/errors/MOSTRA_SHARE_NOT_FOUND.md +23 -0
  154. package/dist/reference/errors/MOSTRA_SHARE_PORTS_EXHAUSTED.md +23 -0
  155. package/dist/reference/errors/MOSTRA_SHARE_TOOL_MISSING.md +23 -0
  156. package/dist/reference/errors/MOSTRA_SHARE_TOOL_NOT_READY.md +23 -0
  157. package/dist/reference/errors/MOSTRA_SHARE_TTL_INVALID.md +23 -0
  158. package/dist/reference/errors/MOSTRA_SHARE_TUNNEL_FAILED.md +23 -0
  159. package/dist/reference/errors/MOSTRA_SMOKE_BUDGET.md +23 -0
  160. package/dist/reference/errors/MOSTRA_SMOKE_NO_EFFECT.md +23 -0
  161. package/dist/reference/errors/MOSTRA_SUBMIT_ALREADY.md +23 -0
  162. package/dist/reference/errors/MOSTRA_SUBMIT_BLOCKED.md +23 -0
  163. package/dist/reference/errors/MOSTRA_SUBMIT_CHANNEL_DENIED.md +23 -0
  164. package/dist/reference/errors/MOSTRA_SUBMIT_NOT_FOUND.md +23 -0
  165. package/dist/reference/errors/MOSTRA_SUBMIT_PAUSED.md +23 -0
  166. package/dist/reference/errors/MOSTRA_SUBMIT_POLICY_NONE.md +23 -0
  167. package/dist/reference/errors/MOSTRA_SUBMIT_REVISION_MOVED.md +23 -0
  168. package/dist/reference/errors/MOSTRA_SUBMIT_SIGNAL_INVALID.md +23 -0
  169. package/dist/reference/errors/MOSTRA_SUBMIT_VIEW_INVALID.md +23 -0
  170. package/dist/reference/errors/MOSTRA_TARGET_UNAVAILABLE.md +23 -0
  171. package/dist/reference/errors/MOSTRA_TEAM_PRESENCE_RATE_LIMITED.md +23 -0
  172. package/dist/reference/errors/MOSTRA_TEAM_ROSTER_POLICY.md +23 -0
  173. package/dist/reference/errors/MOSTRA_TEAM_ROSTER_TOO_LARGE.md +23 -0
  174. package/dist/reference/errors/MOSTRA_TYPE_ERROR.md +23 -0
  175. package/dist/reference/errors/MOSTRA_TYPE_UNTYPED_PACKAGE.md +23 -0
  176. package/dist/reference/errors/MOSTRA_VERIFY_ACTION_SKIPPED.md +23 -0
  177. package/dist/reference/errors/MOSTRA_VERIFY_BASELINE_MISSING.md +23 -0
  178. package/dist/reference/errors/MOSTRA_VERIFY_CRASHED.md +23 -0
  179. package/dist/reference/errors/MOSTRA_VERIFY_LIVE_FAILED.md +23 -0
  180. package/dist/reference/errors/MOSTRA_VERIFY_NO_BASELINE.md +23 -0
  181. package/dist/reference/errors/MOSTRA_VERIFY_SECRET_MISSING.md +23 -0
  182. package/dist/reference/errors/MOSTRA_VERIFY_SKIP_CONSEQUENCE.md +23 -0
  183. package/dist/reference/errors/MOSTRA_VERIFY_TIMEOUT.md +23 -0
  184. package/dist/reference/self-hosting.md +130 -0
  185. package/dist/reference/telemetry.md +84 -0
  186. package/dist/skill/SKILL.md +124 -0
  187. package/dist/skill/assets/examples/dashboard/index.tsx +161 -0
  188. package/dist/skill/assets/examples/dashboard/live.ts +25 -0
  189. package/dist/skill/assets/examples/dashboard/styles.css +125 -0
  190. package/dist/skill/assets/examples/decision/index.tsx +95 -0
  191. package/dist/skill/assets/examples/decision/styles.css +125 -0
  192. package/dist/skill/assets/examples/inbox/actions.ts +23 -0
  193. package/dist/skill/assets/examples/inbox/index.tsx +109 -0
  194. package/dist/skill/assets/examples/inbox/styles.css +125 -0
  195. package/dist/skill/assets/studio.css +125 -0
  196. package/dist/skill/references/answers.md +219 -0
  197. package/dist/skill/references/design.md +154 -0
  198. package/dist/skill/references/libraries.md +167 -0
  199. package/dist/skill/references/long-lived.md +148 -0
  200. package/dist/skill/references/mcp.md +68 -0
  201. package/dist/skill/references/page.md +131 -0
  202. package/dist/skill/references/server.md +146 -0
  203. package/dist/skill/references/sharing.md +123 -0
  204. package/dist/skill/references/teams.md +78 -0
  205. package/dist/skill/references/verify.md +71 -0
  206. package/package.json +10 -5
  207. package/src/gateway/actions.ts +20 -0
  208. package/src/gateway/browser.ts +128 -1
  209. package/src/gateway/capabilities.ts +8 -0
  210. package/src/gateway/http.ts +12 -1
  211. package/src/gateway/index.ts +210 -6
  212. package/src/gateway/listener.ts +31 -6
  213. package/src/gateway/routes.ts +8 -0
  214. package/src/gateway/team.ts +181 -0
  215. package/src/gc/index.ts +5 -0
  216. package/src/instance/index.ts +22 -2
  217. package/src/interaction/ephemeral.ts +21 -0
  218. package/src/interaction/events.ts +17 -0
  219. package/src/interaction/index.ts +325 -20
  220. package/src/interaction/pause.ts +106 -0
  221. package/src/interaction/roster.ts +585 -0
  222. package/src/interaction/submissions.ts +42 -1
  223. package/src/interaction/team.ts +426 -0
  224. package/src/interaction/viewers.ts +34 -1
  225. package/src/interaction/wait.ts +150 -0
  226. package/src/ledger/index.ts +20 -1
  227. package/src/ledger/migrations.ts +86 -0
  228. package/src/link/author.ts +215 -0
  229. package/src/link/hosted.ts +51 -4
  230. package/src/link/http.ts +6 -1
  231. package/src/link/index.ts +3 -1
  232. package/src/link/manager.ts +169 -35
  233. package/src/protocol-server/client.ts +53 -0
  234. package/src/protocol-server/index.ts +1 -1
  235. package/src/server/api.ts +514 -72
  236. package/src/server/auth.ts +600 -74
  237. package/src/server/authorize.ts +816 -0
  238. package/src/server/clients.ts +235 -0
  239. package/src/server/config.ts +7 -0
  240. package/src/server/data.ts +59 -1
  241. package/src/server/directory.ts +91 -0
  242. package/src/server/feed.ts +277 -0
  243. package/src/server/handle.ts +172 -0
  244. package/src/server/hosted-pages.ts +532 -0
  245. package/src/server/hosted.ts +551 -18
  246. package/src/server/index.ts +353 -61
  247. package/src/server/mcp.ts +330 -0
  248. package/src/server/metering.ts +156 -0
  249. package/src/server/oauth-clients.ts +510 -0
  250. package/src/server/operator.ts +557 -0
  251. package/src/server/providers.ts +284 -0
  252. package/src/server/remove.ts +148 -0
  253. package/src/server/routing.ts +275 -0
  254. package/src/share/index.ts +50 -2
  255. package/src/verify/index.ts +7 -0
  256. package/src/verify/runner.ts +27 -2
  257. package/dist/instance-FExcyENK.js.map +0 -1
@@ -0,0 +1,557 @@
1
+ /**
2
+ * The remote server's operator boundary at run time (ARCHITECTURE §15.10, INTERFACES §18.6, D165
3
+ * items 9, 11): the operator module a configuration names, loaded in process, and every call into
4
+ * it. Each call has its time limit and its answer is checked against `@mostra/protocol/operator`'s
5
+ * schemas; a call that throws, times out or answers what the schema refuses counts as no answer,
6
+ * and each port's caller says what no answer means (`limits`: operations that create fail closed,
7
+ * viewer input proceeds; `routing`: nothing is served; `policy`: nothing is added). Outbound
8
+ * deliveries (`metering`, `events`, `invitations`) are kept in the directory's `outbound` table and
9
+ * retried with backoff until the operator takes them, at least once and idempotent by their IDs,
10
+ * across restarts. An invitation is kept by its link's token and handed over with the link built
11
+ * then, so the queue never holds a capability secret (D168).
12
+ *
13
+ * Without an operator module every port is its no-op default, and this module does nothing but
14
+ * answer "allowed".
15
+ */
16
+ import { pathToFileURL } from "node:url";
17
+ import { createDiagnostic, RpcError } from "@mostra/protocol";
18
+ import {
19
+ AccountResolution,
20
+ AuthenticatedCredential,
21
+ type ChatHostPolicy,
22
+ ChatHostPolicy as ChatHostPolicySchema,
23
+ type CredentialResource,
24
+ type IdentityProvider,
25
+ type Invitation,
26
+ LimitAnswer,
27
+ type LimitQuery,
28
+ LinkHost,
29
+ LinkPolicy,
30
+ type LinkQuery,
31
+ type MeterBatch,
32
+ OPERATOR_TIME_LIMITS,
33
+ type OperatorEvent,
34
+ type OperatorPorts,
35
+ PushedAnswer,
36
+ type PushedVersion,
37
+ RoutingAnswer,
38
+ type ServerHandle,
39
+ type SignInIdentity,
40
+ } from "@mostra/protocol/operator";
41
+ import type * as z from "zod";
42
+ import type { Ledger } from "../ledger/index.ts";
43
+ import type { Log } from "../log.ts";
44
+
45
+ /** What `limits` decided: allowed, refused with the operator's words, or no answer in time. */
46
+ export type LimitVerdict =
47
+ | { readonly allowed: true }
48
+ | {
49
+ readonly allowed: false;
50
+ readonly code: string;
51
+ readonly message: string;
52
+ readonly retryAfterMs?: number;
53
+ }
54
+ | { readonly allowed: "unavailable" };
55
+
56
+ /** What `accounts.resolve` decided, or that the server's own accounts decide (no port). */
57
+ export type ResolveVerdict = AccountResolution | { readonly default: true } | "unavailable";
58
+
59
+ /** The operator module at run time. */
60
+ export interface Operator {
61
+ /** Which ports the module implements. */
62
+ readonly has: {
63
+ readonly limits: boolean;
64
+ readonly metering: boolean;
65
+ readonly accounts: boolean;
66
+ readonly authenticate: boolean;
67
+ readonly status: boolean;
68
+ readonly abuse: boolean;
69
+ readonly pushed: boolean;
70
+ readonly policy: boolean;
71
+ readonly routing: boolean;
72
+ readonly linkHost: boolean;
73
+ readonly events: boolean;
74
+ readonly identity: boolean;
75
+ readonly invitations: boolean;
76
+ };
77
+ limit(q: LimitQuery): Promise<LimitVerdict>;
78
+ linkPolicy(q: LinkQuery): Promise<LinkPolicy>;
79
+ chatHost(client: { name: string; redirectHost?: string }): Promise<ChatHostPolicy | null>;
80
+ /** The operator's answer for a host the server doesn't serve itself, or `unavailable`. */
81
+ route(host: string): Promise<RoutingAnswer | "unavailable">;
82
+ /** The shell host a new link of a route is minted on; `null` for the active domain. */
83
+ linkHost(q: { account: string; home: string; routeId: string }): Promise<string | null>;
84
+ /** The identity providers the module supplies now (none on failure). */
85
+ providers(): Promise<readonly IdentityProvider[]>;
86
+ resolve(identity: SignInIdentity, steps: number): Promise<ResolveVerdict>;
87
+ /** An operator-issued credential, or `null` (unknown, refused, or no answer). */
88
+ authenticate(
89
+ bearer: string,
90
+ resource: CredentialResource,
91
+ ): Promise<z.infer<typeof AuthenticatedCredential>>;
92
+ /** An account's status as the operator says, or `undefined` with no answer. */
93
+ status(account: string): Promise<"active" | "suspended" | undefined>;
94
+ report(r: Parameters<NonNullable<OperatorPorts["abuse"]>["report"]>[0]): Promise<void>;
95
+ /** The after-push hook: never blocks serving; its answer may quarantine the version after. */
96
+ pushed(v: PushedVersion, quarantine: (reason: string) => Promise<void>): void;
97
+ /** Keeps an outbound delivery durably, to deliver at least once (INTERFACES §18.6). */
98
+ enqueue(
99
+ item:
100
+ | { readonly port: "events"; readonly event: OperatorEvent }
101
+ | { readonly port: "metering"; readonly batch: MeterBatch }
102
+ | { readonly port: "invitations"; readonly invitation: QueuedInvitation },
103
+ ): void;
104
+ /** Delivers what waits now (tests; the dispatcher does it on its own). */
105
+ flush(): Promise<void>;
106
+ stop(): void;
107
+ }
108
+
109
+ /** Options for {@link loadOperator}. */
110
+ export interface OperatorOptions {
111
+ /** The module's path (`operator` in the configuration), or `undefined` for none. */
112
+ readonly path: string | undefined;
113
+ readonly handle: ServerHandle;
114
+ readonly directory: Ledger;
115
+ readonly log: Log;
116
+ readonly now?: () => number;
117
+ /** How often the outbound dispatcher looks for work; tests shorten it. */
118
+ readonly dispatchMs?: number;
119
+ /**
120
+ * A personal link's URL, built from its token when an invitation is handed over (D168), or
121
+ * `undefined` when the link no longer works (revoked, expired, replaced): the queue never holds
122
+ * the URL, whose fragment is the link's secret.
123
+ */
124
+ readonly invitationLink?: (
125
+ home: string,
126
+ tokenId: string,
127
+ ) => Promise<{ readonly url: string; readonly expiresAt?: string } | undefined>;
128
+ }
129
+
130
+ /** An invitation as the outbound queue keeps it: its link's token, never the link (D168). */
131
+ export type QueuedInvitation = Omit<Invitation, "url" | "expiresAt"> & { readonly tokenId: string };
132
+
133
+ function configInvalid(message: string): RpcError {
134
+ return new RpcError(createDiagnostic("MOSTRA_REMOTE_CONFIG_INVALID", { message }));
135
+ }
136
+
137
+ class Timeout extends Error {}
138
+
139
+ /** Races a call against its time limit. */
140
+ async function within<T>(limitMs: number, call: () => T | Promise<T>): Promise<T> {
141
+ let timer: NodeJS.Timeout | undefined;
142
+ try {
143
+ return await Promise.race([
144
+ Promise.resolve().then(call),
145
+ new Promise<never>((_, reject) => {
146
+ timer = setTimeout(() => reject(new Timeout(`no answer within ${limitMs} ms`)), limitMs);
147
+ timer.unref();
148
+ }),
149
+ ]);
150
+ } finally {
151
+ if (timer) clearTimeout(timer);
152
+ }
153
+ }
154
+
155
+ /** The longest an outbound delivery waits between attempts. */
156
+ const OUTBOUND_MAX_BACKOFF_MS = 5 * 60_000;
157
+
158
+ /**
159
+ * Loads the operator module a configuration names and starts its outbound dispatcher. A module
160
+ * that can't be loaded, or whose default export isn't a function, stops the server before it
161
+ * serves anything (`MOSTRA_REMOTE_CONFIG_INVALID`, naming `operator`).
162
+ */
163
+ export async function loadOperator(options: OperatorOptions): Promise<Operator> {
164
+ const { log, directory } = options;
165
+ const now = options.now ?? (() => Date.now());
166
+ let ports: OperatorPorts = {};
167
+ if (options.path !== undefined) {
168
+ let loaded: { default?: unknown };
169
+ try {
170
+ loaded = (await import(pathToFileURL(options.path).href)) as { default?: unknown };
171
+ } catch (error) {
172
+ throw configInvalid(
173
+ `The configuration key \`operator\` names a module that can't be loaded: ${(error as Error).message}.`,
174
+ );
175
+ }
176
+ if (typeof loaded.default !== "function") {
177
+ throw configInvalid(
178
+ "The configuration key `operator` names a module whose default export isn't a function of the server's handle.",
179
+ );
180
+ }
181
+ try {
182
+ ports = ((await (loaded.default as (server: ServerHandle) => unknown)(options.handle)) ??
183
+ {}) as OperatorPorts;
184
+ } catch (error) {
185
+ throw configInvalid(
186
+ `The operator module's default export failed: ${(error as Error).message}.`,
187
+ );
188
+ }
189
+ if (typeof ports !== "object") {
190
+ throw configInvalid("The operator module's default export didn't return its ports.");
191
+ }
192
+ log.info("operator.loaded", {
193
+ ports: Object.keys(ports).filter((key) => (ports as Record<string, unknown>)[key]),
194
+ });
195
+ }
196
+
197
+ /** One call into the module: time-limited, its answer checked; `undefined` for no answer. */
198
+ const ask = async <T>(
199
+ port: string,
200
+ limitMs: number,
201
+ schema: z.ZodType<T>,
202
+ call: () => unknown,
203
+ ): Promise<{ readonly value: T } | undefined> => {
204
+ try {
205
+ const answer = await within(limitMs, call);
206
+ const checked = schema.safeParse(answer);
207
+ if (!checked.success) {
208
+ log.warn("operator.answer_refused", {
209
+ port,
210
+ issue: checked.error.issues[0]?.message ?? "invalid",
211
+ });
212
+ return undefined;
213
+ }
214
+ return { value: checked.data };
215
+ } catch (error) {
216
+ log.warn("operator.no_answer", {
217
+ port,
218
+ why: error instanceof Timeout ? "timeout" : "error",
219
+ message: (error as Error).message,
220
+ });
221
+ return undefined;
222
+ }
223
+ };
224
+
225
+ /** Answers the operator allowed to keep, by key, until their time. */
226
+ const cache = new Map<string, { readonly value: unknown; readonly until: number }>();
227
+ const cached = <T>(key: string): T | undefined => {
228
+ const hit = cache.get(key);
229
+ if (!hit) return undefined;
230
+ if (hit.until <= now()) {
231
+ cache.delete(key);
232
+ return undefined;
233
+ }
234
+ return hit.value as T;
235
+ };
236
+ const keep = (key: string, value: unknown, forMs: number | undefined): void => {
237
+ if (forMs === undefined || forMs <= 0) return;
238
+ if (cache.size >= 10_000) cache.delete(cache.keys().next().value as string);
239
+ cache.set(key, { value, until: now() + forMs });
240
+ };
241
+
242
+ // ── outbound ────────────────────────────────────────────────────────────────────────────
243
+
244
+ let dispatching: Promise<void> | undefined;
245
+ const deliverOne = async (row: {
246
+ id: string;
247
+ port: string;
248
+ payload_json: string;
249
+ attempts: number;
250
+ }): Promise<void> => {
251
+ const payload = JSON.parse(row.payload_json) as unknown;
252
+ try {
253
+ if (row.port === "invitations") {
254
+ const { tokenId, ...invitation } = payload as QueuedInvitation;
255
+ // Building the link opens its home: bounded like the hand-over, so a home that hangs
256
+ // can't stall the dispatcher (Opus review 4).
257
+ const link = await within(OPERATOR_TIME_LIMITS.outbound, () =>
258
+ options.invitationLink?.(invitation.home, tokenId),
259
+ );
260
+ if (link === undefined) {
261
+ // The link stopped working before it was handed over: inviting with it would mail a
262
+ // dead link, and a later one gets an invitation of its own.
263
+ directory.write((db) => db.run("DELETE FROM outbound WHERE id = ?", row.id));
264
+ log.info("operator.invitation_dropped", { invitationId: invitation.invitationId });
265
+ return;
266
+ }
267
+ await within(OPERATOR_TIME_LIMITS.outbound, () =>
268
+ ports.invitations?.send({
269
+ ...invitation,
270
+ url: link.url,
271
+ ...(link.expiresAt !== undefined ? { expiresAt: link.expiresAt } : {}),
272
+ }),
273
+ );
274
+ } else {
275
+ await within(OPERATOR_TIME_LIMITS.outbound, () =>
276
+ row.port === "events"
277
+ ? ports.events?.deliver(payload as OperatorEvent)
278
+ : ports.metering?.record(payload as MeterBatch),
279
+ );
280
+ }
281
+ directory.write((db) => db.run("DELETE FROM outbound WHERE id = ?", row.id));
282
+ } catch (error) {
283
+ const delay = Math.min(OUTBOUND_MAX_BACKOFF_MS, 1_000 * 2 ** Math.min(row.attempts, 20));
284
+ directory.write((db) =>
285
+ db.run(
286
+ "UPDATE outbound SET attempts = attempts + 1, next_attempt_at = ? WHERE id = ?",
287
+ new Date(now() + delay).toISOString(),
288
+ row.id,
289
+ ),
290
+ );
291
+ log.warn("operator.outbound_failed", {
292
+ port: row.port,
293
+ attempts: row.attempts + 1,
294
+ message: (error as Error).message,
295
+ });
296
+ }
297
+ };
298
+ const dispatch = (): Promise<void> => {
299
+ dispatching ??= (async () => {
300
+ // Yield first: a turn that found nothing would otherwise end, and clear `dispatching`,
301
+ // before `??=` stored it, leaving a finished turn registered for ever (WP-29 met the same).
302
+ await Promise.resolve();
303
+ try {
304
+ for (;;) {
305
+ // The oldest rows of each ordered port, due or not: a port whose oldest delivery waits
306
+ // for its retry waits whole, so an operator sees a home's events in the order they
307
+ // happened. Invitations have no order: each waits for its own retry and none holds
308
+ // another back, so one home that can't build its links never stops the server's
309
+ // other invitations (Opus review 4).
310
+ const due = new Date(now()).toISOString();
311
+ type Row = {
312
+ id: string;
313
+ port: string;
314
+ payload_json: string;
315
+ attempts: number;
316
+ next_attempt_at: string;
317
+ };
318
+ const rows = directory.read((db) => [
319
+ ...(["events", "metering"] as const).flatMap((port) =>
320
+ db.all<Row>(
321
+ "SELECT id, port, payload_json, attempts, next_attempt_at FROM outbound WHERE port = ? ORDER BY rowid LIMIT 50",
322
+ port,
323
+ ),
324
+ ),
325
+ ...db.all<Row>(
326
+ "SELECT id, port, payload_json, attempts, next_attempt_at FROM outbound WHERE port = 'invitations' AND next_attempt_at <= ? ORDER BY rowid LIMIT 50",
327
+ due,
328
+ ),
329
+ ]);
330
+ if (rows.every((row) => row.next_attempt_at > due)) return;
331
+ const blocked = new Set<string>();
332
+ let delivered = 0;
333
+ for (const row of rows) {
334
+ if (blocked.has(row.port)) continue;
335
+ if (row.next_attempt_at > due) {
336
+ blocked.add(row.port);
337
+ continue;
338
+ }
339
+ const before = row.attempts;
340
+ await deliverOne(row);
341
+ const still = directory.read((db) =>
342
+ db.get<{ attempts: number }>("SELECT attempts FROM outbound WHERE id = ?", row.id),
343
+ );
344
+ if (still && still.attempts > before) {
345
+ if (row.port !== "invitations") blocked.add(row.port);
346
+ } else delivered += 1;
347
+ }
348
+ if (delivered === 0) return;
349
+ }
350
+ } finally {
351
+ dispatching = undefined;
352
+ }
353
+ })();
354
+ return dispatching;
355
+ };
356
+ const timer =
357
+ ports.events || ports.metering || ports.invitations
358
+ ? setInterval(() => void dispatch(), options.dispatchMs ?? 1_000)
359
+ : undefined;
360
+ timer?.unref();
361
+
362
+ const has = {
363
+ limits: typeof ports.limits?.check === "function",
364
+ metering: typeof ports.metering?.record === "function",
365
+ accounts: typeof ports.accounts?.resolve === "function",
366
+ authenticate: typeof ports.accounts?.authenticate === "function",
367
+ status: typeof ports.accounts?.status === "function",
368
+ abuse: typeof ports.abuse?.report === "function",
369
+ pushed: typeof ports.abuse?.pushed === "function",
370
+ policy: typeof ports.policy?.link === "function",
371
+ routing: typeof ports.routing?.resolve === "function",
372
+ linkHost: typeof ports.routing?.linkHost === "function",
373
+ events: typeof ports.events?.deliver === "function",
374
+ identity: typeof ports.identity?.providers === "function",
375
+ invitations: typeof ports.invitations?.send === "function",
376
+ };
377
+
378
+ return {
379
+ has,
380
+
381
+ async limit(q) {
382
+ if (!has.limits) return { allowed: true };
383
+ const key = `limits\u0000${JSON.stringify(q)}`;
384
+ const hit = cached<LimitVerdict>(key);
385
+ if (hit) return hit;
386
+ const answer = await ask("limits", OPERATOR_TIME_LIMITS.limits, LimitAnswer, () =>
387
+ ports.limits?.check(q),
388
+ );
389
+ if (!answer) return { allowed: "unavailable" };
390
+ const verdict: LimitVerdict = answer.value.allowed
391
+ ? { allowed: true }
392
+ : {
393
+ allowed: false,
394
+ code: answer.value.code,
395
+ message: answer.value.message,
396
+ ...(answer.value.retryAfterMs !== undefined
397
+ ? { retryAfterMs: answer.value.retryAfterMs }
398
+ : {}),
399
+ };
400
+ keep(key, verdict, answer.value.cacheForMs);
401
+ return verdict;
402
+ },
403
+
404
+ async linkPolicy(q) {
405
+ if (!has.policy) return {};
406
+ const key = `policy\u0000${q.routeId}\u0000${q.tokenId ?? ""}`;
407
+ const hit = cached<LinkPolicy>(key);
408
+ if (hit) return hit;
409
+ const answer = await ask("policy", OPERATOR_TIME_LIMITS.policy, LinkPolicy, () =>
410
+ ports.policy?.link(q),
411
+ );
412
+ if (!answer) return {};
413
+ keep(key, answer.value, answer.value.cacheForMs);
414
+ return answer.value;
415
+ },
416
+
417
+ async chatHost(client) {
418
+ if (typeof ports.policy?.chatHost !== "function") return null;
419
+ const answer = await ask(
420
+ "policy.chatHost",
421
+ OPERATOR_TIME_LIMITS.policy,
422
+ ChatHostPolicySchema.nullable(),
423
+ () => ports.policy?.chatHost?.(client),
424
+ );
425
+ return answer?.value ?? null;
426
+ },
427
+
428
+ async route(host) {
429
+ if (!has.routing) return null;
430
+ const key = `routing\u0000${host}`;
431
+ const hit = cache.get(key);
432
+ if (hit && hit.until > now()) return hit.value as RoutingAnswer;
433
+ const answer = await ask("routing", OPERATOR_TIME_LIMITS.routing, RoutingAnswer, () =>
434
+ ports.routing?.resolve(host),
435
+ );
436
+ if (!answer) return "unavailable";
437
+ keep(key, answer.value, answer.value?.cacheForMs);
438
+ return answer.value;
439
+ },
440
+
441
+ async linkHost(q) {
442
+ if (!has.linkHost) return null;
443
+ const answer = await ask("routing.linkHost", OPERATOR_TIME_LIMITS.routing, LinkHost, () =>
444
+ ports.routing?.linkHost?.(q),
445
+ );
446
+ return answer?.value ?? null;
447
+ },
448
+
449
+ async providers() {
450
+ if (!has.identity) return [];
451
+ try {
452
+ const found = await within(OPERATOR_TIME_LIMITS.identity, () =>
453
+ ports.identity?.providers(),
454
+ );
455
+ return (Array.isArray(found) ? found : []).filter(
456
+ (provider: IdentityProvider) =>
457
+ typeof provider?.id === "string" &&
458
+ /^[a-z][a-z0-9-]{0,31}$/.test(provider.id) &&
459
+ typeof provider.authorize === "function" &&
460
+ typeof provider.callback === "function",
461
+ );
462
+ } catch (error) {
463
+ log.warn("operator.no_answer", { port: "identity", message: (error as Error).message });
464
+ return [];
465
+ }
466
+ },
467
+
468
+ async resolve(identity, steps) {
469
+ if (!has.accounts) return { default: true };
470
+ const answer = await ask(
471
+ "accounts.resolve",
472
+ OPERATOR_TIME_LIMITS.accounts,
473
+ AccountResolution,
474
+ () => ports.accounts?.resolve(identity, { steps }),
475
+ );
476
+ return answer ? answer.value : "unavailable";
477
+ },
478
+
479
+ async authenticate(bearer, resource) {
480
+ if (!has.authenticate) return null;
481
+ const answer = await ask(
482
+ "accounts.authenticate",
483
+ OPERATOR_TIME_LIMITS.authenticate,
484
+ AuthenticatedCredential,
485
+ () => ports.accounts?.authenticate?.(bearer, { resource }),
486
+ );
487
+ return answer?.value ?? null;
488
+ },
489
+
490
+ async status(account) {
491
+ if (typeof ports.accounts?.status !== "function") return undefined;
492
+ try {
493
+ const found = await within(OPERATOR_TIME_LIMITS.accounts, () =>
494
+ ports.accounts?.status?.(account),
495
+ );
496
+ return found === "active" || found === "suspended" ? found : undefined;
497
+ } catch {
498
+ return undefined;
499
+ }
500
+ },
501
+
502
+ async report(r) {
503
+ if (!has.abuse) return;
504
+ try {
505
+ await within(OPERATOR_TIME_LIMITS.policy * 5, () => ports.abuse?.report(r));
506
+ } catch (error) {
507
+ log.warn("operator.no_answer", { port: "abuse.report", message: (error as Error).message });
508
+ }
509
+ },
510
+
511
+ pushed(v, quarantine) {
512
+ if (!has.pushed) return;
513
+ void ask("abuse.pushed", OPERATOR_TIME_LIMITS.pushed, PushedAnswer, () =>
514
+ ports.abuse?.pushed?.(v),
515
+ ).then(async (answer) => {
516
+ const reason = answer?.value?.quarantine?.reason;
517
+ if (reason !== undefined) {
518
+ await quarantine(reason).catch((error: unknown) =>
519
+ log.error("operator.quarantine_failed", { error }),
520
+ );
521
+ }
522
+ });
523
+ },
524
+
525
+ enqueue(item) {
526
+ if (!has[item.port]) return;
527
+ const id =
528
+ item.port === "events"
529
+ ? item.event.eventId
530
+ : item.port === "metering"
531
+ ? item.batch.batchId
532
+ : item.invitation.invitationId;
533
+ const payload =
534
+ item.port === "events"
535
+ ? item.event
536
+ : item.port === "metering"
537
+ ? item.batch
538
+ : item.invitation;
539
+ directory.write((db) =>
540
+ db.run(
541
+ "INSERT OR IGNORE INTO outbound (id, port, payload_json, attempts, next_attempt_at) VALUES (?, ?, ?, 0, ?)",
542
+ `${item.port}:${id}`,
543
+ item.port,
544
+ JSON.stringify(payload),
545
+ new Date(now()).toISOString(),
546
+ ),
547
+ );
548
+ void dispatch();
549
+ },
550
+
551
+ flush: () => dispatch(),
552
+
553
+ stop() {
554
+ if (timer) clearInterval(timer);
555
+ },
556
+ };
557
+ }