@mostra/protocol 0.12.0 → 0.13.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.
@@ -65,8 +65,8 @@ const remoteDiagnostics = {
65
65
  title: "Too many runs wait for the owner",
66
66
  hint: "Wait for the owner to come back and work through its queue, then press again.",
67
67
  docs: {
68
- explanation: "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.",
69
- 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."
68
+ explanation: "The artifact's owner instance is offline and as many runs as the server allows already wait for it, or the server's operator allows no more waiting runs for this account now (its `limits` port, `run.wait`, whose message is the operator's own), so this one was refused before anything was recorded. Runs already waiting keep their place.",
69
+ 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, or the operator's limit its message names; its `Retry-After`, when present, says when to try again."
70
70
  }
71
71
  },
72
72
  MOSTRA_REMOTE_NOT_OWNER_INSTANCE: {
@@ -1 +1 @@
1
- {"version":3,"file":"remote.js","names":[],"sources":["../../../src/diagnostics/codes/remote.ts"],"sourcesContent":["/**\n * Diagnostic codes of the REMOTE area.\n */\nimport type { AreaCatalog } from \"../spec.ts\";\n\n/** The codes of the REMOTE area, in the order they were added. */\nexport const remoteDiagnosticCodes = [\n \"MOSTRA_REMOTE_CONFIG_INVALID\",\n \"MOSTRA_REMOTE_LOGIN_FAILED\",\n \"MOSTRA_REMOTE_UNREACHABLE\",\n \"MOSTRA_REMOTE_OWNER_OFFLINE\",\n \"MOSTRA_REMOTE_QUEUE_FULL\",\n \"MOSTRA_REMOTE_NOT_OWNER_INSTANCE\",\n \"MOSTRA_REMOTE_SIGN_IN_REQUIRED\",\n \"MOSTRA_REMOTE_RATE_LIMITED\",\n \"MOSTRA_REMOTE_PAUSED_BY_OPERATOR\",\n \"MOSTRA_REMOTE_LIMIT_REACHED\",\n \"MOSTRA_REMOTE_OPERATOR_UNAVAILABLE\",\n \"MOSTRA_REMOTE_NO_INSTANCE\",\n \"MOSTRA_REMOTE_UNDER_REVIEW\",\n \"MOSTRA_REMOTE_HOME_SUSPENDED\",\n \"MOSTRA_REMOTE_HOME_MOVING\",\n // gen:codes\n] as const;\n\n/** The codes of the REMOTE area. */\nexport type RemoteDiagnosticCode = (typeof remoteDiagnosticCodes)[number];\n\n/** The REMOTE area's catalog entries. */\nexport const remoteDiagnostics: AreaCatalog<RemoteDiagnosticCode> = {\n MOSTRA_REMOTE_CONFIG_INVALID: {\n severity: \"error\",\n phase: \"host\",\n title: \"Remote server configuration can't be used\",\n hint: \"Fix the configuration key the message names, then start mostra-runtime server again.\",\n docs: {\n explanation:\n \"`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.\",\n fix: \"Correct the key the message names: `apiOrigin` must be an `https:` origin (or `http:` on loopback), and `domains.active` a host name.\",\n },\n },\n MOSTRA_REMOTE_LOGIN_FAILED: {\n severity: \"error\",\n phase: \"host\",\n title: \"Signing in to a remote server failed\",\n hint: \"Run mostra login again, and approve the code on the server's page within ten minutes.\",\n docs: {\n explanation:\n \"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.\",\n 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.\",\n },\n },\n MOSTRA_REMOTE_UNREACHABLE: {\n severity: \"error\",\n phase: \"host\",\n title: \"The remote server can't be reached\",\n hint: \"Check the network and the server's address, then try again; mostra status shows the link.\",\n docs: {\n explanation:\n \"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.\",\n fix: \"Run `mostra status` to see each server's link. When the server is back the link reconnects by itself; then write again.\",\n },\n },\n MOSTRA_REMOTE_OWNER_OFFLINE: {\n severity: \"error\",\n phase: \"host\",\n title: \"The artifact's owner instance is offline\",\n hint: \"Start Mostra on the machine that shared the page, or try again once it is back.\",\n docs: {\n explanation:\n \"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.\",\n 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\"`.',\n },\n },\n MOSTRA_REMOTE_QUEUE_FULL: {\n severity: \"error\",\n phase: \"host\",\n title: \"Too many runs wait for the owner\",\n hint: \"Wait for the owner to come back and work through its queue, then press again.\",\n docs: {\n explanation:\n \"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.\",\n 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.\",\n },\n },\n MOSTRA_REMOTE_NOT_OWNER_INSTANCE: {\n severity: \"error\",\n phase: \"host\",\n title: \"Another instance owns this hosted artifact\",\n hint: \"Share or push this artifact from its owner instance, named in the message.\",\n docs: {\n explanation:\n \"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.\",\n fix: \"Run the command on the instance the message names. Moving an artifact to another owner instance isn't part of this release.\",\n },\n },\n MOSTRA_REMOTE_SIGN_IN_REQUIRED: {\n severity: \"error\",\n phase: \"host\",\n title: \"This action needs a signed-in viewer\",\n hint: \"Sign in from the page's chrome, or have the owner allow this for anyone with the link.\",\n docs: {\n explanation:\n \"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.\",\n 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).',\n },\n },\n MOSTRA_REMOTE_RATE_LIMITED: {\n severity: \"error\",\n phase: \"host\",\n title: \"Too many requests on this link\",\n hint: \"Try again after the time the answer's Retry-After gives.\",\n docs: {\n explanation:\n \"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.\",\n fix: \"Wait for the `Retry-After` the answer carries and try again. The limits are the server's `rateLimits` settings.\",\n },\n },\n MOSTRA_REMOTE_PAUSED_BY_OPERATOR: {\n severity: \"error\",\n phase: \"host\",\n title: \"Paused by the server's operator\",\n hint: \"Contact the server's operator: only the operator resumes a pause it made.\",\n docs: {\n explanation:\n \"The server's operator paused this hosted artifact, and an owner can't undo an operator's pause (D165 item 14). Views keep working and the links stay valid.\",\n fix: \"Ask the server's operator why it was paused and to resume it.\",\n },\n },\n MOSTRA_REMOTE_LIMIT_REACHED: {\n severity: \"error\",\n phase: \"host\",\n title: \"The server's limit refused this\",\n hint: \"Read the message for the server's limit, and try again once it allows the operation.\",\n docs: {\n explanation:\n \"The server's operator refused the operation for this account (its `limits` port): a share, a version push, a link, a view, a submission, an action or an MCP call. The message is the operator's own. A refused submission keeps its draft.\",\n fix: \"Follow the operator's message; its `Retry-After`, when present, says when to try again.\",\n },\n },\n MOSTRA_REMOTE_OPERATOR_UNAVAILABLE: {\n severity: \"error\",\n phase: \"host\",\n title: \"The server's operator didn't answer\",\n hint: \"Try again in a moment; the server's operator didn't answer in time.\",\n docs: {\n explanation:\n \"The server's operator module didn't answer in time (2 s for limits, 5 s for sign-in), so an operation that creates something (a share, a push, a link, authoring, a sign-in) was refused rather than allowed blind. Views, drafts and submissions never wait for it, and existing sessions keep working.\",\n fix: \"Try again; if it lasts, the server's operator has to fix its operator module.\",\n },\n },\n MOSTRA_REMOTE_NO_INSTANCE: {\n severity: \"error\",\n phase: \"host\",\n title: \"No owner instance connected\",\n hint: \"Start Mostra on the machine linked to this account (mostra daemon start), then try again.\",\n docs: {\n explanation:\n \"Creating, verifying and publishing from a chat host run on the account's default owner instance, through the relay (D165 item 5), and no default instance is connected to the server now. Reading tools (list, wait, results, state, docs, open) keep working.\",\n fix: \"Start Mostra on the linked machine (`mostra daemon start`, or `mostra daemon install` to keep it running); link a machine first with `mostra login <server> --default`.\",\n },\n },\n MOSTRA_REMOTE_UNDER_REVIEW: {\n severity: \"error\",\n phase: \"host\",\n title: \"This page is under review\",\n hint: \"Nothing to do here: the server's operator is reviewing this page.\",\n docs: {\n explanation:\n \"The server's operator quarantined this hosted page, or this version of it, while it reviews it. Its data is kept; the page shows a neutral notice instead of its content until the operator releases it.\",\n fix: \"The owner can ask the server's operator about the review.\",\n },\n },\n MOSTRA_REMOTE_HOME_SUSPENDED: {\n severity: \"error\",\n phase: \"host\",\n title: \"This account's pages are suspended\",\n hint: \"Contact the server's operator: this account's pages are suspended.\",\n docs: {\n explanation:\n \"The server's operator suspended this account's hosted home: its pages, its owner instances' bindings, pushes and links are refused until the operator resumes it. Nothing was deleted.\",\n fix: \"Ask the server's operator to resume the account.\",\n },\n },\n MOSTRA_REMOTE_HOME_MOVING: {\n severity: \"error\",\n phase: \"host\",\n title: \"This account's pages are moving\",\n hint: \"Try again in a minute: this account's pages are moving between machines.\",\n docs: {\n explanation:\n \"The server's operator is moving this account's hosted home to another data directory (`drainHome`), so the home is closed here until it serves again. Clients retry; nothing is lost.\",\n fix: \"Retry shortly; the move ends when the operator releases the home on its new machine.\",\n },\n },\n // gen:entries\n};\n"],"mappings":";;AAMA,MAAa,wBAAwB;CACnC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AAEF;;AAMA,MAAa,oBAAuD;CAClE,8BAA8B;EAC5B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,4BAA4B;EAC1B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,2BAA2B;EACzB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,6BAA6B;EAC3B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,0BAA0B;EACxB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,kCAAkC;EAChC,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,gCAAgC;EAC9B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,4BAA4B;EAC1B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,kCAAkC;EAChC,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,6BAA6B;EAC3B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,oCAAoC;EAClC,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,2BAA2B;EACzB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,4BAA4B;EAC1B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,8BAA8B;EAC5B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,2BAA2B;EACzB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;AAEF"}
1
+ {"version":3,"file":"remote.js","names":[],"sources":["../../../src/diagnostics/codes/remote.ts"],"sourcesContent":["/**\n * Diagnostic codes of the REMOTE area.\n */\nimport type { AreaCatalog } from \"../spec.ts\";\n\n/** The codes of the REMOTE area, in the order they were added. */\nexport const remoteDiagnosticCodes = [\n \"MOSTRA_REMOTE_CONFIG_INVALID\",\n \"MOSTRA_REMOTE_LOGIN_FAILED\",\n \"MOSTRA_REMOTE_UNREACHABLE\",\n \"MOSTRA_REMOTE_OWNER_OFFLINE\",\n \"MOSTRA_REMOTE_QUEUE_FULL\",\n \"MOSTRA_REMOTE_NOT_OWNER_INSTANCE\",\n \"MOSTRA_REMOTE_SIGN_IN_REQUIRED\",\n \"MOSTRA_REMOTE_RATE_LIMITED\",\n \"MOSTRA_REMOTE_PAUSED_BY_OPERATOR\",\n \"MOSTRA_REMOTE_LIMIT_REACHED\",\n \"MOSTRA_REMOTE_OPERATOR_UNAVAILABLE\",\n \"MOSTRA_REMOTE_NO_INSTANCE\",\n \"MOSTRA_REMOTE_UNDER_REVIEW\",\n \"MOSTRA_REMOTE_HOME_SUSPENDED\",\n \"MOSTRA_REMOTE_HOME_MOVING\",\n // gen:codes\n] as const;\n\n/** The codes of the REMOTE area. */\nexport type RemoteDiagnosticCode = (typeof remoteDiagnosticCodes)[number];\n\n/** The REMOTE area's catalog entries. */\nexport const remoteDiagnostics: AreaCatalog<RemoteDiagnosticCode> = {\n MOSTRA_REMOTE_CONFIG_INVALID: {\n severity: \"error\",\n phase: \"host\",\n title: \"Remote server configuration can't be used\",\n hint: \"Fix the configuration key the message names, then start mostra-runtime server again.\",\n docs: {\n explanation:\n \"`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.\",\n fix: \"Correct the key the message names: `apiOrigin` must be an `https:` origin (or `http:` on loopback), and `domains.active` a host name.\",\n },\n },\n MOSTRA_REMOTE_LOGIN_FAILED: {\n severity: \"error\",\n phase: \"host\",\n title: \"Signing in to a remote server failed\",\n hint: \"Run mostra login again, and approve the code on the server's page within ten minutes.\",\n docs: {\n explanation:\n \"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.\",\n 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.\",\n },\n },\n MOSTRA_REMOTE_UNREACHABLE: {\n severity: \"error\",\n phase: \"host\",\n title: \"The remote server can't be reached\",\n hint: \"Check the network and the server's address, then try again; mostra status shows the link.\",\n docs: {\n explanation:\n \"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.\",\n fix: \"Run `mostra status` to see each server's link. When the server is back the link reconnects by itself; then write again.\",\n },\n },\n MOSTRA_REMOTE_OWNER_OFFLINE: {\n severity: \"error\",\n phase: \"host\",\n title: \"The artifact's owner instance is offline\",\n hint: \"Start Mostra on the machine that shared the page, or try again once it is back.\",\n docs: {\n explanation:\n \"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.\",\n 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\"`.',\n },\n },\n MOSTRA_REMOTE_QUEUE_FULL: {\n severity: \"error\",\n phase: \"host\",\n title: \"Too many runs wait for the owner\",\n hint: \"Wait for the owner to come back and work through its queue, then press again.\",\n docs: {\n explanation:\n \"The artifact's owner instance is offline and as many runs as the server allows already wait for it, or the server's operator allows no more waiting runs for this account now (its `limits` port, `run.wait`, whose message is the operator's own), so this one was refused before anything was recorded. Runs already waiting keep their place.\",\n 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, or the operator's limit its message names; its `Retry-After`, when present, says when to try again.\",\n },\n },\n MOSTRA_REMOTE_NOT_OWNER_INSTANCE: {\n severity: \"error\",\n phase: \"host\",\n title: \"Another instance owns this hosted artifact\",\n hint: \"Share or push this artifact from its owner instance, named in the message.\",\n docs: {\n explanation:\n \"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.\",\n fix: \"Run the command on the instance the message names. Moving an artifact to another owner instance isn't part of this release.\",\n },\n },\n MOSTRA_REMOTE_SIGN_IN_REQUIRED: {\n severity: \"error\",\n phase: \"host\",\n title: \"This action needs a signed-in viewer\",\n hint: \"Sign in from the page's chrome, or have the owner allow this for anyone with the link.\",\n docs: {\n explanation:\n \"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.\",\n 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).',\n },\n },\n MOSTRA_REMOTE_RATE_LIMITED: {\n severity: \"error\",\n phase: \"host\",\n title: \"Too many requests on this link\",\n hint: \"Try again after the time the answer's Retry-After gives.\",\n docs: {\n explanation:\n \"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.\",\n fix: \"Wait for the `Retry-After` the answer carries and try again. The limits are the server's `rateLimits` settings.\",\n },\n },\n MOSTRA_REMOTE_PAUSED_BY_OPERATOR: {\n severity: \"error\",\n phase: \"host\",\n title: \"Paused by the server's operator\",\n hint: \"Contact the server's operator: only the operator resumes a pause it made.\",\n docs: {\n explanation:\n \"The server's operator paused this hosted artifact, and an owner can't undo an operator's pause (D165 item 14). Views keep working and the links stay valid.\",\n fix: \"Ask the server's operator why it was paused and to resume it.\",\n },\n },\n MOSTRA_REMOTE_LIMIT_REACHED: {\n severity: \"error\",\n phase: \"host\",\n title: \"The server's limit refused this\",\n hint: \"Read the message for the server's limit, and try again once it allows the operation.\",\n docs: {\n explanation:\n \"The server's operator refused the operation for this account (its `limits` port): a share, a version push, a link, a view, a submission, an action or an MCP call. The message is the operator's own. A refused submission keeps its draft.\",\n fix: \"Follow the operator's message; its `Retry-After`, when present, says when to try again.\",\n },\n },\n MOSTRA_REMOTE_OPERATOR_UNAVAILABLE: {\n severity: \"error\",\n phase: \"host\",\n title: \"The server's operator didn't answer\",\n hint: \"Try again in a moment; the server's operator didn't answer in time.\",\n docs: {\n explanation:\n \"The server's operator module didn't answer in time (2 s for limits, 5 s for sign-in), so an operation that creates something (a share, a push, a link, authoring, a sign-in) was refused rather than allowed blind. Views, drafts and submissions never wait for it, and existing sessions keep working.\",\n fix: \"Try again; if it lasts, the server's operator has to fix its operator module.\",\n },\n },\n MOSTRA_REMOTE_NO_INSTANCE: {\n severity: \"error\",\n phase: \"host\",\n title: \"No owner instance connected\",\n hint: \"Start Mostra on the machine linked to this account (mostra daemon start), then try again.\",\n docs: {\n explanation:\n \"Creating, verifying and publishing from a chat host run on the account's default owner instance, through the relay (D165 item 5), and no default instance is connected to the server now. Reading tools (list, wait, results, state, docs, open) keep working.\",\n fix: \"Start Mostra on the linked machine (`mostra daemon start`, or `mostra daemon install` to keep it running); link a machine first with `mostra login <server> --default`.\",\n },\n },\n MOSTRA_REMOTE_UNDER_REVIEW: {\n severity: \"error\",\n phase: \"host\",\n title: \"This page is under review\",\n hint: \"Nothing to do here: the server's operator is reviewing this page.\",\n docs: {\n explanation:\n \"The server's operator quarantined this hosted page, or this version of it, while it reviews it. Its data is kept; the page shows a neutral notice instead of its content until the operator releases it.\",\n fix: \"The owner can ask the server's operator about the review.\",\n },\n },\n MOSTRA_REMOTE_HOME_SUSPENDED: {\n severity: \"error\",\n phase: \"host\",\n title: \"This account's pages are suspended\",\n hint: \"Contact the server's operator: this account's pages are suspended.\",\n docs: {\n explanation:\n \"The server's operator suspended this account's hosted home: its pages, its owner instances' bindings, pushes and links are refused until the operator resumes it. Nothing was deleted.\",\n fix: \"Ask the server's operator to resume the account.\",\n },\n },\n MOSTRA_REMOTE_HOME_MOVING: {\n severity: \"error\",\n phase: \"host\",\n title: \"This account's pages are moving\",\n hint: \"Try again in a minute: this account's pages are moving between machines.\",\n docs: {\n explanation:\n \"The server's operator is moving this account's hosted home to another data directory (`drainHome`), so the home is closed here until it serves again. Clients retry; nothing is lost.\",\n fix: \"Retry shortly; the move ends when the operator releases the home on its new machine.\",\n },\n },\n // gen:entries\n};\n"],"mappings":";;AAMA,MAAa,wBAAwB;CACnC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AAEF;;AAMA,MAAa,oBAAuD;CAClE,8BAA8B;EAC5B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,4BAA4B;EAC1B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,2BAA2B;EACzB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,6BAA6B;EAC3B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,0BAA0B;EACxB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,kCAAkC;EAChC,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,gCAAgC;EAC9B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,4BAA4B;EAC1B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,kCAAkC;EAChC,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,6BAA6B;EAC3B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,oCAAoC;EAClC,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,2BAA2B;EACzB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,4BAA4B;EAC1B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,8BAA8B;EAC5B,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;CACA,2BAA2B;EACzB,UAAU;EACV,OAAO;EACP,OAAO;EACP,MAAM;EACN,MAAM;GACJ,aACE;GACF,KAAK;EACP;CACF;AAEF"}
@@ -15,8 +15,14 @@ export declare const OPERATOR_TIME_LIMITS: {
15
15
  };
16
16
  /**
17
17
  * An operation `limits.check` judges. When the operator doesn't answer in time, `share`,
18
- * `version.push`, `link` and authoring fail closed, and `view`, `submit` and draft writes proceed,
19
- * so nothing a person typed is lost (D165 item 9).
18
+ * `version.push`, `link` and authoring fail closed, and `view`, `submit`, draft writes and relayed
19
+ * actions (`run`, `run.wait`, `call`) proceed, so nothing a person typed or pressed is lost (D165
20
+ * item 9).
21
+ *
22
+ * - `run`: a relayed action run is about to be recorded (quantity 1). A request that joins a run
23
+ * already recorded (its key or client key) is never asked.
24
+ * - `run.wait`: that run would wait for its owner, who is away (quantity 1), asked after `run`.
25
+ * - `call`: a plain call is about to be relayed to the owner (quantity 1).
20
26
  */
21
27
  export type LimitOperation = "share" | "version.push" | "link" | "view" | "submit" | "run" | "run.wait" | "call" | "mcp.call" | "storage";
22
28
  /** What `limits.check` is asked. */
@@ -29,9 +35,15 @@ export interface LimitQuery {
29
35
  readonly artifact?: string;
30
36
  /** The artifact's hosted route, for operations on one (WP-30). */
31
37
  readonly routeId?: string;
38
+ /**
39
+ * The version being pushed, on `version.push` and `storage` (MT-03): a push that takes several
40
+ * rounds (the owner uploads the files it was told are missing, then pushes again) asks about the
41
+ * same version each round, so an operator counting versions counts this ID once.
42
+ */
43
+ readonly versionId?: string;
32
44
  /** What is asked for. */
33
45
  readonly operation: LimitOperation;
34
- /** How much: bytes for `storage` and `version.push`, else 1. */
46
+ /** How much: bytes for `storage`, else 1. */
35
47
  readonly quantity?: number;
36
48
  }
37
49
  /** How long the server may keep an answer instead of asking again, in milliseconds (WP-30). */
@@ -52,8 +64,14 @@ export type LimitAnswer = ({
52
64
  } & Cacheable);
53
65
  /** The schema the server checks `limits.check`'s answer against. */
54
66
  export declare const LimitAnswer: z.ZodType<LimitAnswer>;
55
- /** A counter's name (INTERFACES §18.6). */
56
- export type MeterName = "views" | "submissions" | "requests" | "bytes.stored" | "bytes.egress" | "relay.messages" | "mcp.calls" | "home.activeSeconds" | (string & {});
67
+ /**
68
+ * A counter's name (INTERFACES §18.6). `bytes.stored` sums the client bytes a home uploads in a
69
+ * window; `bytes.held` is a level, not a sum: the client bytes a home holds, each file once however
70
+ * many of its versions name it, sent in the window after it changes (so it falls to what is left,
71
+ * and to 0 once, when content is removed), and for every home holding anything at the first window
72
+ * after a server starts and once a day (MT-03). Keep the latest value per home.
73
+ */
74
+ export type MeterName = "views" | "submissions" | "requests" | "bytes.stored" | "bytes.held" | "bytes.egress" | "relay.messages" | "mcp.calls" | "home.activeSeconds" | (string & {});
57
75
  /**
58
76
  * One counter of a batch. `views` carry `viewerKey`, a monthly pseudonymous key (an HMAC under a
59
77
  * key the server rotates each month), never an identity: per account for a signed-in viewer, per
@@ -90,7 +108,10 @@ export interface MeterBatch {
90
108
  }
91
109
  /**
92
110
  * Who an identity provider says signed in (INTERFACES §18.5). `facts` carries what a provider
93
- * tells beyond that (GitHub's account age, `createdAt`), for an operator's policy.
111
+ * tells beyond that, for an operator's policy: the built-in GitHub adapter gives `login`, the
112
+ * account's age (`createdAt`) and its public counts (`publicRepos`, `publicGists`, `followers`, from
113
+ * the same lookup, MT-03); the OpenID Connect adapter gives the ID token's claims its configuration
114
+ * names (`claims`, such as a Google Workspace account's domain `hd`), each under its own name.
94
115
  */
95
116
  export interface SignInIdentity {
96
117
  /** The provider's ID (`IdentityProvider.id`). */
@@ -103,7 +124,7 @@ export interface SignInIdentity {
103
124
  readonly emailVerified?: boolean;
104
125
  /** The display name the provider gives. */
105
126
  readonly name?: string;
106
- /** What else the provider tells (an account's age as `createdAt`). */
127
+ /** What else the provider tells (an account's age as `createdAt`, chosen claims). */
107
128
  readonly facts?: Readonly<Record<string, unknown>>;
108
129
  }
109
130
  /** The schema the server checks a provider's `SignInIdentity` against. */
@@ -133,6 +154,17 @@ export interface IdentityProvider {
133
154
  readonly id: string;
134
155
  /** What the sign-in page calls it ("GitHub"). */
135
156
  readonly label: string;
157
+ /**
158
+ * Whether the provider verifies the names it gives, and the label a hosted page's sender line
159
+ * shows for it ("verified with Acme"; 1 to 64 characters, shown as text). Absent: a person who
160
+ * signs in through it is shown "name not verified". The server records the label on the sign-in
161
+ * identity when the provider links or signs in that person, so renaming or retiring the provider
162
+ * later changes no name already verified (MT-03). The built-in providers verify, but for the
163
+ * development one.
164
+ */
165
+ readonly verifies?: {
166
+ readonly label: string;
167
+ };
136
168
  /** Where to send the person: the provider's authorization URL with `state` and PKCE. */
137
169
  authorize(state: string, pkce: SignInPkce, context: SignInContext): string | Promise<string>;
138
170
  /**
@@ -261,7 +293,10 @@ export interface LinkPolicy extends Cacheable {
261
293
  };
262
294
  /** The longest a link may live from when it was minted. */
263
295
  readonly maxTtl?: string;
264
- /** A link unused for this long expires. */
296
+ /**
297
+ * A link without a view for this long expires: judged from its last view before the one being
298
+ * opened (or from its minting), so a fresh visit to an idle link is refused as well (MT-03).
299
+ */
265
300
  readonly idleExpiry?: string;
266
301
  /** The line after "Your answer was sent.", as text. */
267
302
  readonly afterSubmit?: string;
@@ -1 +1 @@
1
- {"version":3,"file":"operator.d.ts","names":[],"sources":["../src/operator.ts"],"mappings":"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"}
1
+ {"version":3,"file":"operator.d.ts","names":[],"sources":["../src/operator.ts"],"mappings":"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"}
@@ -1 +1 @@
1
- {"version":3,"file":"operator.js","names":[],"sources":["../src/operator.ts"],"sourcesContent":["/**\n * The operator boundary of a remote server (ARCHITECTURE §15.10, INTERFACES §18.6, D165 items 9\n * and 11): the ports an operating layer implements in an ES module the server loads in process,\n * and the handle the server gives it. Each port is optional and has a no-op default, so a\n * self-hoster needs none of it; each call is async and time-limited, and the server checks every\n * answer against the schemas below before it acts on one (an answer they refuse counts as no\n * answer).\n *\n * An operating layer imports nothing of Mostra but this module (`@mostra/protocol/operator`), so\n * the surface it builds on is this file's, versioned with `@mostra/protocol` and changed only\n * additively (D32).\n *\n * ```ts\n * import { defineOperator } from \"@mostra/protocol/operator\";\n *\n * export default defineOperator((server) => ({\n * limits: { check: async (q) => (q.operation === \"share\" ? { allowed: true } : { allowed: true }) },\n * abuse: { report: async (r) => { await server.quarantine({ routeId: r.routeId }, r.reason); } },\n * }));\n * ```\n *\n * Every port call and every handle target names a hosted route (`rte_…`): an artifact ID, and a\n * version ID derived from it (D89), repeat across homes when a project is copied, so a bare ID\n * would reach every tenant hosting it.\n */\nimport * as z from \"zod\";\n\n/** The operator boundary's own revision, which a module may check (additive within it). */\nexport const OPERATOR_REVISION = \"2026-11-08\";\n\n/** How long the server waits for each port, in milliseconds, before it acts as if none answered. */\nexport const OPERATOR_TIME_LIMITS: {\n readonly limits: number;\n readonly policy: number;\n readonly routing: number;\n readonly identity: number;\n readonly accounts: number;\n readonly authenticate: number;\n readonly pushed: number;\n readonly outbound: number;\n} = {\n limits: 2_000,\n policy: 2_000,\n routing: 2_000,\n identity: 2_000,\n accounts: 5_000,\n authenticate: 5_000,\n pushed: 30_000,\n outbound: 30_000,\n};\n\n// ── limits ──────────────────────────────────────────────────────────────────────────────\n\n/**\n * An operation `limits.check` judges. When the operator doesn't answer in time, `share`,\n * `version.push`, `link` and authoring fail closed, and `view`, `submit` and draft writes proceed,\n * so nothing a person typed is lost (D165 item 9).\n */\nexport type LimitOperation =\n | \"share\"\n | \"version.push\"\n | \"link\"\n | \"view\"\n | \"submit\"\n | \"run\"\n | \"run.wait\"\n | \"call\"\n | \"mcp.call\"\n | \"storage\";\n\n/** What `limits.check` is asked. */\nexport interface LimitQuery {\n /** The account the operation counts against. */\n readonly account: string;\n /** The account's hosted home. */\n readonly home: string;\n /** The artifact, for operations on one. */\n readonly artifact?: string;\n /** The artifact's hosted route, for operations on one (WP-30). */\n readonly routeId?: string;\n /** What is asked for. */\n readonly operation: LimitOperation;\n /** How much: bytes for `storage` and `version.push`, else 1. */\n readonly quantity?: number;\n}\n\n/** How long the server may keep an answer instead of asking again, in milliseconds (WP-30). */\nexport interface Cacheable {\n /** Absent or 0: ask again next time. */\n readonly cacheForMs?: number;\n}\n\n/** `limits.check`'s answer. */\nexport type LimitAnswer =\n | ({ readonly allowed: true } & Cacheable)\n | ({\n readonly allowed: false;\n /** A diagnostic code of the operator's (the server answers `MOSTRA_REMOTE_LIMIT_REACHED`). */\n readonly code: string;\n /** Shown as text to whoever was refused. */\n readonly message: string;\n readonly retryAfterMs?: number;\n } & Cacheable);\n\nconst cacheFor = z.int().min(0).max(86_400_000).exactOptional();\n\n/** The schema the server checks `limits.check`'s answer against. */\nexport const LimitAnswer: z.ZodType<LimitAnswer> = z.union([\n z.object({ allowed: z.literal(true), cacheForMs: cacheFor }),\n z.object({\n allowed: z.literal(false),\n code: z.string().min(1).max(128),\n message: z.string().max(1_000),\n retryAfterMs: z.int().min(0).max(86_400_000).exactOptional(),\n cacheForMs: cacheFor,\n }),\n]);\n\n// ── metering ────────────────────────────────────────────────────────────────────────────\n\n/** A counter's name (INTERFACES §18.6). */\nexport type MeterName =\n | \"views\"\n | \"submissions\"\n | \"requests\"\n | \"bytes.stored\"\n | \"bytes.egress\"\n | \"relay.messages\"\n | \"mcp.calls\"\n | \"home.activeSeconds\"\n | (string & {});\n\n/**\n * One counter of a batch. `views` carry `viewerKey`, a monthly pseudonymous key (an HMAC under a\n * key the server rotates each month), never an identity: per account for a signed-in viewer, per\n * viewer for a link minted with one, and per route for an anonymous viewer, since the shell gives\n * each route a different key and none spans routes (HY-08). `mcp.calls` carry `client`, the MCP\n * client's `clientInfo` name (D148).\n */\nexport interface MeterCounter {\n /** What is counted. */\n readonly name: MeterName;\n /** The account it counts against. */\n readonly account: string;\n /** The account's hosted home. */\n readonly home?: string;\n /** The artifact, for counters of one. */\n readonly artifactId?: string;\n /** The artifact's hosted route, for counters of one. */\n readonly routeId?: string;\n /** How much in the batch's window: a count, bytes or seconds. */\n readonly value: number;\n /** What tells counters of one name apart (`viewerKey`, `client`). */\n readonly dimensions?: Readonly<Record<string, string>>;\n}\n\n/** What `metering.record` receives, at least once, idempotent by `batchId`. */\nexport interface MeterBatch {\n /** Stable across retries: a batch delivered twice is the same batch. */\n readonly batchId: string;\n /** Where the window the counters cover starts. */\n readonly from: string;\n /** Where it ends. */\n readonly to: string;\n /** The counters, one per name, account, route and dimensions. */\n readonly counters: readonly MeterCounter[];\n}\n\n// ── sign-in: identity providers and accounts ────────────────────────────────────────────\n\n/**\n * Who an identity provider says signed in (INTERFACES §18.5). `facts` carries what a provider\n * tells beyond that (GitHub's account age, `createdAt`), for an operator's policy.\n */\nexport interface SignInIdentity {\n /** The provider's ID (`IdentityProvider.id`). */\n readonly provider: string;\n /** The provider's own stable ID for the person. */\n readonly subject: string;\n /** The person's email address, when the provider gives one. */\n readonly email?: string;\n /** Whether the provider verified `email`. */\n readonly emailVerified?: boolean;\n /** The display name the provider gives. */\n readonly name?: string;\n /** What else the provider tells (an account's age as `createdAt`). */\n readonly facts?: Readonly<Record<string, unknown>>;\n}\n\n/** The schema the server checks a provider's `SignInIdentity` against. */\nexport const SignInIdentity: z.ZodType<SignInIdentity> = z.object({\n provider: z.string().regex(/^[a-z][a-z0-9-]{0,31}$/),\n subject: z.string().min(1).max(256),\n email: z.string().max(320).exactOptional(),\n emailVerified: z.boolean().exactOptional(),\n name: z.string().max(256).exactOptional(),\n facts: z.record(z.string(), z.unknown()).exactOptional(),\n});\n\n/** PKCE for one sign-in at a provider: the server makes it; the provider sends `challenge`. */\nexport interface SignInPkce {\n /** The S256 challenge the provider's authorization request carries. */\n readonly challenge: string;\n /** Always S256. */\n readonly method: \"S256\";\n /** The verifier the provider's code exchange sends. */\n readonly verifier: string;\n}\n\n/** What a provider's `authorize` and `callback` are told about the sign-in in progress. */\nexport interface SignInContext {\n /** The provider's return address on the API origin: `<apiOrigin>/signin/<id>/callback`. */\n readonly redirectUri: string;\n /** A fresh value an OpenID Connect provider binds its ID token to. */\n readonly nonce: string;\n}\n\n/**\n * An identity provider behind the sign-in port (D165 item 8): the built-in OpenID Connect and\n * GitHub adapters, a development one for tests, or one an operator module supplies.\n */\nexport interface IdentityProvider {\n /** Lower-case letters, digits and hyphens, at most 32: part of its callback's path. */\n readonly id: string;\n /** What the sign-in page calls it (\"GitHub\"). */\n readonly label: string;\n /** Where to send the person: the provider's authorization URL with `state` and PKCE. */\n authorize(state: string, pkce: SignInPkce, context: SignInContext): string | Promise<string>;\n /**\n * The person the provider names on return, from its callback's query (each parameter once; a\n * repeated one is refused before this is called). The server has already\n * checked `state`; the provider exchanges the code (with `pkce.verifier`) and checks what it\n * gets. Throws when sign-in failed.\n */\n callback(\n params: Readonly<Record<string, string>>,\n context: SignInContext & { readonly state: string; readonly pkce: SignInPkce },\n ): Promise<SignInIdentity>;\n}\n\n/**\n * `accounts.resolve`'s answer: the account (`status` `suspended` refuses sign-in), a **first\n * sign-in step** on the operator's origin, or a refusal shown as text.\n *\n * A step: the server sends the person to `step.url` with `mostra_return` added, an address on the\n * API origin (`/signin/return?step=<handle>`). The handle is single-use, lasts 15 minutes and is\n * bound to the browser that started the sign-in (a `__Host-` cookie on the API origin, never on a\n * user-content domain), so it can't be replayed or swapped. When the person comes back the server\n * calls `resolve` again with the same identity and `context.steps` one higher; at most three steps\n * per sign-in (WP-30, D167).\n */\nexport type AccountResolution =\n | {\n readonly account: string;\n readonly name?: string;\n readonly status: \"active\" | \"suspended\";\n }\n | { readonly step: { readonly url: string } }\n | { readonly refused: { readonly message: string } };\n\n/** The schema the server checks `accounts.resolve`'s answer against. */\nexport const AccountResolution: z.ZodType<AccountResolution> = z.union([\n z.object({\n account: z.string().min(1).max(128),\n name: z.string().max(256).exactOptional(),\n status: z.enum([\"active\", \"suspended\"]),\n }),\n z.object({ step: z.object({ url: z.url({ protocol: /^https$/ }).max(2_048) }) }),\n z.object({ refused: z.object({ message: z.string().max(1_000) }) }),\n]);\n\n/** Where an operator-issued credential was presented (D165 item 9, Opus review of WP-28). */\nexport type CredentialResource = \"host\" | \"mcp\" | \"files\";\n\n/**\n * `accounts.authenticate`'s answer for a credential the operator issued, or `null`. `subject`\n * names the credential stably (a service key's ID): a binding with it is one owner instance link\n * of the account, kept per subject, so a program can run an always-on owner instance.\n */\nexport interface AuthenticatedCredential {\n /** The account the credential acts for. */\n readonly account: string;\n /** What it may do: `mostra` for everything a sign-in may. */\n readonly scope: readonly string[];\n /** The credential's own stable name, which keys its instance link. */\n readonly subject?: string;\n}\n\n/** The schema the server checks `accounts.authenticate`'s answer against. */\nexport const AuthenticatedCredential: z.ZodType<AuthenticatedCredential | null> = z\n .object({\n account: z.string().min(1).max(128),\n scope: z.array(z.string().max(64)).max(32),\n subject: z\n .string()\n .regex(/^[A-Za-z0-9._:-]{1,128}$/)\n .exactOptional(),\n })\n .nullable();\n\n// ── abuse ───────────────────────────────────────────────────────────────────────────────\n\n/** A report from the shell's report control (`POST /a/{routeId}/_mostra/report`). */\nexport interface AbuseReport {\n /** The reported route. */\n readonly routeId: string;\n /** The route's label. */\n readonly label: string;\n /** The artifact's own ID (as its manifest names it). */\n readonly artifactId: string;\n /** The hosted home. */\n readonly home: string;\n /** The version the reporter saw, when the shell knew it. */\n readonly versionId?: string;\n /** The reason the reporter chose. */\n readonly reason: string;\n /** What the reporter wrote, as text. */\n readonly detail?: string;\n /** When the report was made. */\n readonly at: string;\n}\n\n/** What `abuse.pushed` receives after each version push, with read access to its client files. */\nexport interface PushedVersion {\n /** The route the version was pushed to. */\n readonly routeId: string;\n /** The route's label. */\n readonly label: string;\n /** The artifact's own ID (as its manifest names it). */\n readonly artifactId: string;\n /** The hosted home. */\n readonly home: string;\n /** The pushed version. */\n readonly versionId: string;\n /** The version's `manifest.json`, parsed. */\n readonly manifest: unknown;\n /** Every client file's path (`client/…`). */\n readonly files: readonly string[];\n /** A client file's bytes, by its path in the listing. */\n read(path: string): Promise<Uint8Array>;\n}\n\n/** `abuse.pushed`'s answer: quarantine the version, or nothing. */\nexport type PushedAnswer = { readonly quarantine?: { readonly reason: string } } | undefined;\n\n/** The schema the server checks `abuse.pushed`'s answer against. */\nexport const PushedAnswer: z.ZodType<PushedAnswer> = z\n .object({ quarantine: z.object({ reason: z.string().max(1_000) }).exactOptional() })\n .optional();\n\n// ── policy ──────────────────────────────────────────────────────────────────────────────\n\n/** What `policy.link` is asked about one link of one route. */\nexport interface LinkQuery {\n /** The account that owns the route. */\n readonly account: string;\n /** Its hosted home. */\n readonly home: string;\n /** The route. */\n readonly routeId: string;\n /** The artifact's own ID (as its manifest names it). */\n readonly artifactId: string;\n /** The link, once it exists. */\n readonly tokenId?: string;\n}\n\n/**\n * Per link and artifact (D161): an interstitial before the page, the longest link lifetime and an\n * idle expiry (durations such as `7d`), the after-submit line, the footer's wording (it can't be\n * hidden on a public link), and the made-with mark.\n */\nexport interface LinkPolicy extends Cacheable {\n /** A page the shell shows before the artifact, once per browser and link; its message as text. */\n readonly interstitial?: { readonly kind: string; readonly message?: string };\n /** The longest a link may live from when it was minted. */\n readonly maxTtl?: string;\n /** A link unused for this long expires. */\n readonly idleExpiry?: string;\n /** The line after \"Your answer was sent.\", as text. */\n readonly afterSubmit?: string;\n /** The footer's wording in place of \"Never enter passwords\", as text. */\n readonly footer?: string;\n /** Whether the made-with mark shows, and where it links. */\n readonly madeWith?: { readonly show: boolean; readonly href?: string };\n}\n\nconst duration = z.string().regex(/^[1-9][0-9]{0,8}[smhd]$/);\n\n/** The schema the server checks `policy.link`'s answer against. */\nexport const LinkPolicy: z.ZodType<LinkPolicy> = z.object({\n interstitial: z\n .object({ kind: z.string().min(1).max(64), message: z.string().max(2_000).exactOptional() })\n .exactOptional(),\n maxTtl: duration.exactOptional(),\n idleExpiry: duration.exactOptional(),\n afterSubmit: z.string().max(500).exactOptional(),\n footer: z.string().min(1).max(500).exactOptional(),\n madeWith: z\n .object({ show: z.boolean(), href: z.url({ protocol: /^https$/ }).exactOptional() })\n .exactOptional(),\n cacheForMs: cacheFor,\n});\n\n/**\n * How Mostra behaves in one chat host (D160): how a page renders there (an MCP App resource, or\n * the hosted link), and what a reached limit may say (`limit-reached` only, or the operator's\n * message).\n */\nexport interface ChatHostPolicy {\n /** `app`: through the MCP Apps resource; `link`: the hosted link only. */\n readonly render?: \"app\" | \"link\";\n /** What a reached limit may say there. */\n readonly quota?: \"limit-reached\" | \"message\";\n}\n\n/** The schema of the `ChatHostPolicy` type, for configuration and `policy.chatHost`. */\nexport const ChatHostPolicy: z.ZodType<ChatHostPolicy> = z.object({\n render: z.enum([\"app\", \"link\"]).exactOptional(),\n quota: z.enum([\"limit-reached\", \"message\"]).exactOptional(),\n});\n\n// ── routing ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * `routing.resolve`'s answer for an exact `Host` the server doesn't serve by itself (any host but\n * a configured user-content domain's apex and its routes' labels):\n *\n * - `shell`: the host shows the hosted shell (`/a/<routeId>`) for one home's routes, whose frames\n * are served on `<route label>.<domain>`. `domain` is a configured user-content domain, or one\n * the operator supplies (an organization's own, whose TLS the operator's edge terminates for the\n * host and every label under `domain`); the server serves those labels once the host is\n * recorded, without asking again.\n * - `route`: the host shows the shell of one route only (`/a/<routeId>`), with its frames on its\n * label under the active domain: a chosen, readable name.\n * - `null`: nothing is served (421).\n *\n * A host the operator supplies is recorded like the server's own labels, bound to its home\n * forever: never issued to another home, so no origin's storage passes between tenants (D165).\n */\nexport type RoutingAnswer =\n | ({ readonly shell: { readonly domain: string; readonly home: string } } & Cacheable)\n | ({ readonly route: { readonly home: string; readonly routeId: string } } & Cacheable)\n | null;\n\n/**\n * A host name of at least two labels, lower case; a port only as a local test server's hosts carry\n * one (the server's own configuration allows the same).\n */\nconst hostName = z\n .string()\n .regex(\n /^(?=.{1,253}(:|$))[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+(:\\d{1,5})?$/,\n );\n\n/** The schema the server checks `routing.resolve`'s answer against. */\nexport const RoutingAnswer: z.ZodType<RoutingAnswer> = z.union([\n z.object({\n shell: z.object({ domain: hostName, home: z.string().min(1) }),\n cacheForMs: cacheFor,\n }),\n z.object({\n route: z.object({ home: z.string().min(1), routeId: z.string().min(1) }),\n cacheForMs: cacheFor,\n }),\n z.null(),\n]);\n\n/** The schema of `routing.linkHost`'s answer: a shell host, or `null` for the active domain. */\nexport const LinkHost: z.ZodType<string | null> = hostName.nullable();\n\n// ── events ──────────────────────────────────────────────────────────────────────────────\n\n/** The kind of an outbound event. */\nexport type OperatorEventKind =\n | \"submission.accepted\"\n | \"version.pushed\"\n | \"run.ended\"\n | \"roster.completed\"\n | (string & {});\n\n/**\n * One outbound event, delivered at least once with a stable `eventId`. `payload`:\n * `submission.accepted` carries the submission's `Results` (INTERFACES §8, the `Results` type of `@mostra/protocol`); `version.pushed`\n * `{ versionId, number }`; `run.ended` `{ runId, action, status }`; `roster.completed`\n * `{ round, respondents, submissions: { ref, submissionId }[] }`, when every expected respondent\n * answered (D168).\n * `label` is the route's label, so an operator running several servers behind one front learns\n * which serves which label (WP-30).\n */\nexport interface OperatorEvent {\n /** Stable across retries. */\n readonly eventId: string;\n /** What happened. */\n readonly kind: OperatorEventKind;\n /** The account that owns the route. */\n readonly account: string;\n /** Its hosted home. */\n readonly home: string;\n /** The route. */\n readonly routeId: string;\n /** The route's label. */\n readonly label: string;\n /** The artifact's own ID (as its manifest names it). */\n readonly artifactId: string;\n /** When it happened. */\n readonly at: string;\n /** What the kind carries. */\n readonly payload: unknown;\n}\n\n// ── the module ──────────────────────────────────────────────────────────────────────────\n\n/** The ports an operator module implements; each is optional, with the default named. */\nexport interface OperatorPorts {\n /** Allows or refuses an operation for an account. Default: allow. */\n readonly limits?: { check(q: LimitQuery): Promise<LimitAnswer> };\n /** Counters in batches, at least once. Default: discard. */\n readonly metering?: { record(batch: MeterBatch): Promise<void> };\n /**\n * Identity providers beside the configured ones, asked at each sign-in so the set can change\n * while the server runs (WP-30). Default: none.\n */\n readonly identity?: {\n providers(): Promise<readonly IdentityProvider[]> | readonly IdentityProvider[];\n };\n /**\n * Sign-in identities to accounts, a first sign-in step, and credentials the operator issued.\n * Default: the server's own accounts, no step, no outside credential.\n */\n readonly accounts?: {\n resolve(\n identity: SignInIdentity,\n context: { readonly steps: number },\n ): Promise<AccountResolution>;\n authenticate?(\n bearer: string,\n context: { readonly resource: CredentialResource },\n ): Promise<AuthenticatedCredential | null>;\n status?(account: string): Promise<\"active\" | \"suspended\">;\n };\n /** Reports and the after-push hook. Default: nothing. */\n readonly abuse?: {\n report(r: AbuseReport): Promise<void>;\n pushed?(v: PushedVersion): Promise<PushedAnswer>;\n };\n /** Per link and per chat host. Default: nothing beyond configuration. */\n readonly policy?: {\n link(q: LinkQuery): Promise<LinkPolicy>;\n chatHost?(client: {\n readonly name: string;\n readonly redirectHost?: string;\n }): Promise<ChatHostPolicy | null>;\n };\n /**\n * Hosts the operator supplies, and the host a new link is minted on. Default: the server's own\n * labels, and links on the active domain.\n */\n readonly routing?: {\n resolve(host: string): Promise<RoutingAnswer>;\n /**\n * The shell host a new link of this route is minted on (one `resolve` answers `shell` or\n * `route` for), or `null` for the active domain (WP-30). A link keeps the host it was minted\n * on (D137).\n */\n linkHost?(q: {\n readonly account: string;\n readonly home: string;\n readonly routeId: string;\n }): Promise<string | null>;\n };\n /** Outbound events, at least once with stable IDs. Default: discard. */\n readonly events?: { deliver(e: OperatorEvent): Promise<void> };\n /**\n * Invitations to expected respondents (D121, D168): for each respondent a hosted roster names\n * with an `email`, when they are added or their personal link is replaced, so the operator can\n * mail them their link. At least once, ordered per home, with a stable `invitationId`. No mailer\n * ships: the open server only hands them over. Default: none sent.\n */\n readonly invitations?: { send(invitation: Invitation): Promise<void> };\n}\n\n/**\n * One invitation (D168). `url` is the respondent's personal link, a capability URL whose secret is\n * in its fragment: the server never stores or logs it (it builds it from the link's token when it\n * hands the invitation over), so the operator mails it and keeps it no longer than that.\n */\nexport interface Invitation {\n /** Stable across retries: `<home>:<tokenId>`, one per personal link. */\n readonly invitationId: string;\n /** The account that owns the route. */\n readonly account: string;\n /** Its hosted home. */\n readonly home: string;\n /** The route. */\n readonly routeId: string;\n /** The route's label. */\n readonly label: string;\n /** The artifact's ID. */\n readonly artifactId: string;\n /** The artifact's title, as its latest version names it. */\n readonly title: string;\n /** Who is invited: the owner's key for them, their name and the address to write to. */\n readonly respondent: { readonly ref: string; readonly name?: string; readonly email: string };\n /** Who invites: the owner's display name and the provider that verified it, when one did. */\n readonly sender: { readonly name?: string; readonly verifiedBy?: string };\n /** The personal link. */\n readonly url: string;\n /** When the link stops working, when it has a lifetime. */\n readonly expiresAt?: string;\n /** When the respondent was added, or their link replaced. */\n readonly at: string;\n}\n\n/** A hosted route, or one version of it: what the handle's quarantine and release act on. */\nexport type RouteTarget =\n | { readonly routeId: string }\n | { readonly routeId: string; readonly versionId: string };\n\n/**\n * What the server gives its operator module (INTERFACES §18.6). Every target names a hosted route.\n * Each call is durable when it resolves.\n */\nexport interface ServerHandle {\n /** The operator boundary's revision this server speaks. */\n readonly revision: string;\n /** The server's API origin. */\n readonly apiOrigin: string;\n /** A neutral \"under review\" page from the shell; data kept; `release` restores it. */\n quarantine(target: RouteTarget, reason: string): Promise<void>;\n /** Ends a quarantine. */\n release(target: RouteTarget): Promise<void>;\n /** Views keep working; submissions and relayed actions are refused; only the operator resumes. */\n pause(routeId: string, reason: string): Promise<void>;\n /** Ends an operator's pause (and an owner's, too). */\n resume(routeId: string): Promise<void>;\n /** Refuses the home's bindings, pushes, links and pages until `resumeHome`. */\n suspendHome(home: string, reason: string): Promise<void>;\n /** Ends a suspension. */\n resumeHome(home: string): Promise<void>;\n /** Revokes every link of a route; answers how many were live. */\n revokeLinks(routeId: string): Promise<number>;\n /** Revokes one link (410 from then on). */\n revokeLink(tokenId: string): Promise<void>;\n /** Closes the home and refuses to reopen it, to move it between data directories. */\n drainHome(home: string): Promise<void>;\n /** Serves a drained home again. */\n releaseHome(home: string): Promise<void>;\n /** A restore from a backup: rotates the home's incarnation before it serves anything. */\n restored(home: string): Promise<void>;\n /** Deletion: explicit, never part of another action. The route's label is never issued again. */\n remove(routeId: string): Promise<void>;\n}\n\n/** An operator module's default export. */\nexport type OperatorModule = (server: ServerHandle) => OperatorPorts | Promise<OperatorPorts>;\n\n/** Types an operator module's default export; returns it unchanged. */\nexport function defineOperator(module: OperatorModule): OperatorModule {\n return module;\n}\n"],"mappings":"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"}
1
+ {"version":3,"file":"operator.js","names":[],"sources":["../src/operator.ts"],"sourcesContent":["/**\n * The operator boundary of a remote server (ARCHITECTURE §15.10, INTERFACES §18.6, D165 items 9\n * and 11): the ports an operating layer implements in an ES module the server loads in process,\n * and the handle the server gives it. Each port is optional and has a no-op default, so a\n * self-hoster needs none of it; each call is async and time-limited, and the server checks every\n * answer against the schemas below before it acts on one (an answer they refuse counts as no\n * answer).\n *\n * An operating layer imports nothing of Mostra but this module (`@mostra/protocol/operator`), so\n * the surface it builds on is this file's, versioned with `@mostra/protocol` and changed only\n * additively (D32).\n *\n * ```ts\n * import { defineOperator } from \"@mostra/protocol/operator\";\n *\n * export default defineOperator((server) => ({\n * limits: { check: async (q) => (q.operation === \"share\" ? { allowed: true } : { allowed: true }) },\n * abuse: { report: async (r) => { await server.quarantine({ routeId: r.routeId }, r.reason); } },\n * }));\n * ```\n *\n * Every port call and every handle target names a hosted route (`rte_…`): an artifact ID, and a\n * version ID derived from it (D89), repeat across homes when a project is copied, so a bare ID\n * would reach every tenant hosting it.\n */\nimport * as z from \"zod\";\n\n/** The operator boundary's own revision, which a module may check (additive within it). */\nexport const OPERATOR_REVISION = \"2026-11-08\";\n\n/** How long the server waits for each port, in milliseconds, before it acts as if none answered. */\nexport const OPERATOR_TIME_LIMITS: {\n readonly limits: number;\n readonly policy: number;\n readonly routing: number;\n readonly identity: number;\n readonly accounts: number;\n readonly authenticate: number;\n readonly pushed: number;\n readonly outbound: number;\n} = {\n limits: 2_000,\n policy: 2_000,\n routing: 2_000,\n identity: 2_000,\n accounts: 5_000,\n authenticate: 5_000,\n pushed: 30_000,\n outbound: 30_000,\n};\n\n// ── limits ──────────────────────────────────────────────────────────────────────────────\n\n/**\n * An operation `limits.check` judges. When the operator doesn't answer in time, `share`,\n * `version.push`, `link` and authoring fail closed, and `view`, `submit`, draft writes and relayed\n * actions (`run`, `run.wait`, `call`) proceed, so nothing a person typed or pressed is lost (D165\n * item 9).\n *\n * - `run`: a relayed action run is about to be recorded (quantity 1). A request that joins a run\n * already recorded (its key or client key) is never asked.\n * - `run.wait`: that run would wait for its owner, who is away (quantity 1), asked after `run`.\n * - `call`: a plain call is about to be relayed to the owner (quantity 1).\n */\nexport type LimitOperation =\n | \"share\"\n | \"version.push\"\n | \"link\"\n | \"view\"\n | \"submit\"\n | \"run\"\n | \"run.wait\"\n | \"call\"\n | \"mcp.call\"\n | \"storage\";\n\n/** What `limits.check` is asked. */\nexport interface LimitQuery {\n /** The account the operation counts against. */\n readonly account: string;\n /** The account's hosted home. */\n readonly home: string;\n /** The artifact, for operations on one. */\n readonly artifact?: string;\n /** The artifact's hosted route, for operations on one (WP-30). */\n readonly routeId?: string;\n /**\n * The version being pushed, on `version.push` and `storage` (MT-03): a push that takes several\n * rounds (the owner uploads the files it was told are missing, then pushes again) asks about the\n * same version each round, so an operator counting versions counts this ID once.\n */\n readonly versionId?: string;\n /** What is asked for. */\n readonly operation: LimitOperation;\n /** How much: bytes for `storage`, else 1. */\n readonly quantity?: number;\n}\n\n/** How long the server may keep an answer instead of asking again, in milliseconds (WP-30). */\nexport interface Cacheable {\n /** Absent or 0: ask again next time. */\n readonly cacheForMs?: number;\n}\n\n/** `limits.check`'s answer. */\nexport type LimitAnswer =\n | ({ readonly allowed: true } & Cacheable)\n | ({\n readonly allowed: false;\n /** A diagnostic code of the operator's (the server answers `MOSTRA_REMOTE_LIMIT_REACHED`). */\n readonly code: string;\n /** Shown as text to whoever was refused. */\n readonly message: string;\n readonly retryAfterMs?: number;\n } & Cacheable);\n\nconst cacheFor = z.int().min(0).max(86_400_000).exactOptional();\n\n/** The schema the server checks `limits.check`'s answer against. */\nexport const LimitAnswer: z.ZodType<LimitAnswer> = z.union([\n z.object({ allowed: z.literal(true), cacheForMs: cacheFor }),\n z.object({\n allowed: z.literal(false),\n code: z.string().min(1).max(128),\n message: z.string().max(1_000),\n retryAfterMs: z.int().min(0).max(86_400_000).exactOptional(),\n cacheForMs: cacheFor,\n }),\n]);\n\n// ── metering ────────────────────────────────────────────────────────────────────────────\n\n/**\n * A counter's name (INTERFACES §18.6). `bytes.stored` sums the client bytes a home uploads in a\n * window; `bytes.held` is a level, not a sum: the client bytes a home holds, each file once however\n * many of its versions name it, sent in the window after it changes (so it falls to what is left,\n * and to 0 once, when content is removed), and for every home holding anything at the first window\n * after a server starts and once a day (MT-03). Keep the latest value per home.\n */\nexport type MeterName =\n | \"views\"\n | \"submissions\"\n | \"requests\"\n | \"bytes.stored\"\n | \"bytes.held\"\n | \"bytes.egress\"\n | \"relay.messages\"\n | \"mcp.calls\"\n | \"home.activeSeconds\"\n | (string & {});\n\n/**\n * One counter of a batch. `views` carry `viewerKey`, a monthly pseudonymous key (an HMAC under a\n * key the server rotates each month), never an identity: per account for a signed-in viewer, per\n * viewer for a link minted with one, and per route for an anonymous viewer, since the shell gives\n * each route a different key and none spans routes (HY-08). `mcp.calls` carry `client`, the MCP\n * client's `clientInfo` name (D148).\n */\nexport interface MeterCounter {\n /** What is counted. */\n readonly name: MeterName;\n /** The account it counts against. */\n readonly account: string;\n /** The account's hosted home. */\n readonly home?: string;\n /** The artifact, for counters of one. */\n readonly artifactId?: string;\n /** The artifact's hosted route, for counters of one. */\n readonly routeId?: string;\n /** How much in the batch's window: a count, bytes or seconds. */\n readonly value: number;\n /** What tells counters of one name apart (`viewerKey`, `client`). */\n readonly dimensions?: Readonly<Record<string, string>>;\n}\n\n/** What `metering.record` receives, at least once, idempotent by `batchId`. */\nexport interface MeterBatch {\n /** Stable across retries: a batch delivered twice is the same batch. */\n readonly batchId: string;\n /** Where the window the counters cover starts. */\n readonly from: string;\n /** Where it ends. */\n readonly to: string;\n /** The counters, one per name, account, route and dimensions. */\n readonly counters: readonly MeterCounter[];\n}\n\n// ── sign-in: identity providers and accounts ────────────────────────────────────────────\n\n/**\n * Who an identity provider says signed in (INTERFACES §18.5). `facts` carries what a provider\n * tells beyond that, for an operator's policy: the built-in GitHub adapter gives `login`, the\n * account's age (`createdAt`) and its public counts (`publicRepos`, `publicGists`, `followers`, from\n * the same lookup, MT-03); the OpenID Connect adapter gives the ID token's claims its configuration\n * names (`claims`, such as a Google Workspace account's domain `hd`), each under its own name.\n */\nexport interface SignInIdentity {\n /** The provider's ID (`IdentityProvider.id`). */\n readonly provider: string;\n /** The provider's own stable ID for the person. */\n readonly subject: string;\n /** The person's email address, when the provider gives one. */\n readonly email?: string;\n /** Whether the provider verified `email`. */\n readonly emailVerified?: boolean;\n /** The display name the provider gives. */\n readonly name?: string;\n /** What else the provider tells (an account's age as `createdAt`, chosen claims). */\n readonly facts?: Readonly<Record<string, unknown>>;\n}\n\n/** The schema the server checks a provider's `SignInIdentity` against. */\nexport const SignInIdentity: z.ZodType<SignInIdentity> = z.object({\n provider: z.string().regex(/^[a-z][a-z0-9-]{0,31}$/),\n subject: z.string().min(1).max(256),\n email: z.string().max(320).exactOptional(),\n emailVerified: z.boolean().exactOptional(),\n name: z.string().max(256).exactOptional(),\n facts: z.record(z.string(), z.unknown()).exactOptional(),\n});\n\n/** PKCE for one sign-in at a provider: the server makes it; the provider sends `challenge`. */\nexport interface SignInPkce {\n /** The S256 challenge the provider's authorization request carries. */\n readonly challenge: string;\n /** Always S256. */\n readonly method: \"S256\";\n /** The verifier the provider's code exchange sends. */\n readonly verifier: string;\n}\n\n/** What a provider's `authorize` and `callback` are told about the sign-in in progress. */\nexport interface SignInContext {\n /** The provider's return address on the API origin: `<apiOrigin>/signin/<id>/callback`. */\n readonly redirectUri: string;\n /** A fresh value an OpenID Connect provider binds its ID token to. */\n readonly nonce: string;\n}\n\n/**\n * An identity provider behind the sign-in port (D165 item 8): the built-in OpenID Connect and\n * GitHub adapters, a development one for tests, or one an operator module supplies.\n */\nexport interface IdentityProvider {\n /** Lower-case letters, digits and hyphens, at most 32: part of its callback's path. */\n readonly id: string;\n /** What the sign-in page calls it (\"GitHub\"). */\n readonly label: string;\n /**\n * Whether the provider verifies the names it gives, and the label a hosted page's sender line\n * shows for it (\"verified with Acme\"; 1 to 64 characters, shown as text). Absent: a person who\n * signs in through it is shown \"name not verified\". The server records the label on the sign-in\n * identity when the provider links or signs in that person, so renaming or retiring the provider\n * later changes no name already verified (MT-03). The built-in providers verify, but for the\n * development one.\n */\n readonly verifies?: { readonly label: string };\n /** Where to send the person: the provider's authorization URL with `state` and PKCE. */\n authorize(state: string, pkce: SignInPkce, context: SignInContext): string | Promise<string>;\n /**\n * The person the provider names on return, from its callback's query (each parameter once; a\n * repeated one is refused before this is called). The server has already\n * checked `state`; the provider exchanges the code (with `pkce.verifier`) and checks what it\n * gets. Throws when sign-in failed.\n */\n callback(\n params: Readonly<Record<string, string>>,\n context: SignInContext & { readonly state: string; readonly pkce: SignInPkce },\n ): Promise<SignInIdentity>;\n}\n\n/**\n * `accounts.resolve`'s answer: the account (`status` `suspended` refuses sign-in), a **first\n * sign-in step** on the operator's origin, or a refusal shown as text.\n *\n * A step: the server sends the person to `step.url` with `mostra_return` added, an address on the\n * API origin (`/signin/return?step=<handle>`). The handle is single-use, lasts 15 minutes and is\n * bound to the browser that started the sign-in (a `__Host-` cookie on the API origin, never on a\n * user-content domain), so it can't be replayed or swapped. When the person comes back the server\n * calls `resolve` again with the same identity and `context.steps` one higher; at most three steps\n * per sign-in (WP-30, D167).\n */\nexport type AccountResolution =\n | {\n readonly account: string;\n readonly name?: string;\n readonly status: \"active\" | \"suspended\";\n }\n | { readonly step: { readonly url: string } }\n | { readonly refused: { readonly message: string } };\n\n/** The schema the server checks `accounts.resolve`'s answer against. */\nexport const AccountResolution: z.ZodType<AccountResolution> = z.union([\n z.object({\n account: z.string().min(1).max(128),\n name: z.string().max(256).exactOptional(),\n status: z.enum([\"active\", \"suspended\"]),\n }),\n z.object({ step: z.object({ url: z.url({ protocol: /^https$/ }).max(2_048) }) }),\n z.object({ refused: z.object({ message: z.string().max(1_000) }) }),\n]);\n\n/** Where an operator-issued credential was presented (D165 item 9, Opus review of WP-28). */\nexport type CredentialResource = \"host\" | \"mcp\" | \"files\";\n\n/**\n * `accounts.authenticate`'s answer for a credential the operator issued, or `null`. `subject`\n * names the credential stably (a service key's ID): a binding with it is one owner instance link\n * of the account, kept per subject, so a program can run an always-on owner instance.\n */\nexport interface AuthenticatedCredential {\n /** The account the credential acts for. */\n readonly account: string;\n /** What it may do: `mostra` for everything a sign-in may. */\n readonly scope: readonly string[];\n /** The credential's own stable name, which keys its instance link. */\n readonly subject?: string;\n}\n\n/** The schema the server checks `accounts.authenticate`'s answer against. */\nexport const AuthenticatedCredential: z.ZodType<AuthenticatedCredential | null> = z\n .object({\n account: z.string().min(1).max(128),\n scope: z.array(z.string().max(64)).max(32),\n subject: z\n .string()\n .regex(/^[A-Za-z0-9._:-]{1,128}$/)\n .exactOptional(),\n })\n .nullable();\n\n// ── abuse ───────────────────────────────────────────────────────────────────────────────\n\n/** A report from the shell's report control (`POST /a/{routeId}/_mostra/report`). */\nexport interface AbuseReport {\n /** The reported route. */\n readonly routeId: string;\n /** The route's label. */\n readonly label: string;\n /** The artifact's own ID (as its manifest names it). */\n readonly artifactId: string;\n /** The hosted home. */\n readonly home: string;\n /** The version the reporter saw, when the shell knew it. */\n readonly versionId?: string;\n /** The reason the reporter chose. */\n readonly reason: string;\n /** What the reporter wrote, as text. */\n readonly detail?: string;\n /** When the report was made. */\n readonly at: string;\n}\n\n/** What `abuse.pushed` receives after each version push, with read access to its client files. */\nexport interface PushedVersion {\n /** The route the version was pushed to. */\n readonly routeId: string;\n /** The route's label. */\n readonly label: string;\n /** The artifact's own ID (as its manifest names it). */\n readonly artifactId: string;\n /** The hosted home. */\n readonly home: string;\n /** The pushed version. */\n readonly versionId: string;\n /** The version's `manifest.json`, parsed. */\n readonly manifest: unknown;\n /** Every client file's path (`client/…`). */\n readonly files: readonly string[];\n /** A client file's bytes, by its path in the listing. */\n read(path: string): Promise<Uint8Array>;\n}\n\n/** `abuse.pushed`'s answer: quarantine the version, or nothing. */\nexport type PushedAnswer = { readonly quarantine?: { readonly reason: string } } | undefined;\n\n/** The schema the server checks `abuse.pushed`'s answer against. */\nexport const PushedAnswer: z.ZodType<PushedAnswer> = z\n .object({ quarantine: z.object({ reason: z.string().max(1_000) }).exactOptional() })\n .optional();\n\n// ── policy ──────────────────────────────────────────────────────────────────────────────\n\n/** What `policy.link` is asked about one link of one route. */\nexport interface LinkQuery {\n /** The account that owns the route. */\n readonly account: string;\n /** Its hosted home. */\n readonly home: string;\n /** The route. */\n readonly routeId: string;\n /** The artifact's own ID (as its manifest names it). */\n readonly artifactId: string;\n /** The link, once it exists. */\n readonly tokenId?: string;\n}\n\n/**\n * Per link and artifact (D161): an interstitial before the page, the longest link lifetime and an\n * idle expiry (durations such as `7d`), the after-submit line, the footer's wording (it can't be\n * hidden on a public link), and the made-with mark.\n */\nexport interface LinkPolicy extends Cacheable {\n /** A page the shell shows before the artifact, once per browser and link; its message as text. */\n readonly interstitial?: { readonly kind: string; readonly message?: string };\n /** The longest a link may live from when it was minted. */\n readonly maxTtl?: string;\n /**\n * A link without a view for this long expires: judged from its last view before the one being\n * opened (or from its minting), so a fresh visit to an idle link is refused as well (MT-03).\n */\n readonly idleExpiry?: string;\n /** The line after \"Your answer was sent.\", as text. */\n readonly afterSubmit?: string;\n /** The footer's wording in place of \"Never enter passwords\", as text. */\n readonly footer?: string;\n /** Whether the made-with mark shows, and where it links. */\n readonly madeWith?: { readonly show: boolean; readonly href?: string };\n}\n\nconst duration = z.string().regex(/^[1-9][0-9]{0,8}[smhd]$/);\n\n/** The schema the server checks `policy.link`'s answer against. */\nexport const LinkPolicy: z.ZodType<LinkPolicy> = z.object({\n interstitial: z\n .object({ kind: z.string().min(1).max(64), message: z.string().max(2_000).exactOptional() })\n .exactOptional(),\n maxTtl: duration.exactOptional(),\n idleExpiry: duration.exactOptional(),\n afterSubmit: z.string().max(500).exactOptional(),\n footer: z.string().min(1).max(500).exactOptional(),\n madeWith: z\n .object({ show: z.boolean(), href: z.url({ protocol: /^https$/ }).exactOptional() })\n .exactOptional(),\n cacheForMs: cacheFor,\n});\n\n/**\n * How Mostra behaves in one chat host (D160): how a page renders there (an MCP App resource, or\n * the hosted link), and what a reached limit may say (`limit-reached` only, or the operator's\n * message).\n */\nexport interface ChatHostPolicy {\n /** `app`: through the MCP Apps resource; `link`: the hosted link only. */\n readonly render?: \"app\" | \"link\";\n /** What a reached limit may say there. */\n readonly quota?: \"limit-reached\" | \"message\";\n}\n\n/** The schema of the `ChatHostPolicy` type, for configuration and `policy.chatHost`. */\nexport const ChatHostPolicy: z.ZodType<ChatHostPolicy> = z.object({\n render: z.enum([\"app\", \"link\"]).exactOptional(),\n quota: z.enum([\"limit-reached\", \"message\"]).exactOptional(),\n});\n\n// ── routing ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * `routing.resolve`'s answer for an exact `Host` the server doesn't serve by itself (any host but\n * a configured user-content domain's apex and its routes' labels):\n *\n * - `shell`: the host shows the hosted shell (`/a/<routeId>`) for one home's routes, whose frames\n * are served on `<route label>.<domain>`. `domain` is a configured user-content domain, or one\n * the operator supplies (an organization's own, whose TLS the operator's edge terminates for the\n * host and every label under `domain`); the server serves those labels once the host is\n * recorded, without asking again.\n * - `route`: the host shows the shell of one route only (`/a/<routeId>`), with its frames on its\n * label under the active domain: a chosen, readable name.\n * - `null`: nothing is served (421).\n *\n * A host the operator supplies is recorded like the server's own labels, bound to its home\n * forever: never issued to another home, so no origin's storage passes between tenants (D165).\n */\nexport type RoutingAnswer =\n | ({ readonly shell: { readonly domain: string; readonly home: string } } & Cacheable)\n | ({ readonly route: { readonly home: string; readonly routeId: string } } & Cacheable)\n | null;\n\n/**\n * A host name of at least two labels, lower case; a port only as a local test server's hosts carry\n * one (the server's own configuration allows the same).\n */\nconst hostName = z\n .string()\n .regex(\n /^(?=.{1,253}(:|$))[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+(:\\d{1,5})?$/,\n );\n\n/** The schema the server checks `routing.resolve`'s answer against. */\nexport const RoutingAnswer: z.ZodType<RoutingAnswer> = z.union([\n z.object({\n shell: z.object({ domain: hostName, home: z.string().min(1) }),\n cacheForMs: cacheFor,\n }),\n z.object({\n route: z.object({ home: z.string().min(1), routeId: z.string().min(1) }),\n cacheForMs: cacheFor,\n }),\n z.null(),\n]);\n\n/** The schema of `routing.linkHost`'s answer: a shell host, or `null` for the active domain. */\nexport const LinkHost: z.ZodType<string | null> = hostName.nullable();\n\n// ── events ──────────────────────────────────────────────────────────────────────────────\n\n/** The kind of an outbound event. */\nexport type OperatorEventKind =\n | \"submission.accepted\"\n | \"version.pushed\"\n | \"run.ended\"\n | \"roster.completed\"\n | (string & {});\n\n/**\n * One outbound event, delivered at least once with a stable `eventId`. `payload`:\n * `submission.accepted` carries the submission's `Results` (INTERFACES §8, the `Results` type of `@mostra/protocol`); `version.pushed`\n * `{ versionId, number }`; `run.ended` `{ runId, action, status }`; `roster.completed`\n * `{ round, respondents, submissions: { ref, submissionId }[] }`, when every expected respondent\n * answered (D168).\n * `label` is the route's label, so an operator running several servers behind one front learns\n * which serves which label (WP-30).\n */\nexport interface OperatorEvent {\n /** Stable across retries. */\n readonly eventId: string;\n /** What happened. */\n readonly kind: OperatorEventKind;\n /** The account that owns the route. */\n readonly account: string;\n /** Its hosted home. */\n readonly home: string;\n /** The route. */\n readonly routeId: string;\n /** The route's label. */\n readonly label: string;\n /** The artifact's own ID (as its manifest names it). */\n readonly artifactId: string;\n /** When it happened. */\n readonly at: string;\n /** What the kind carries. */\n readonly payload: unknown;\n}\n\n// ── the module ──────────────────────────────────────────────────────────────────────────\n\n/** The ports an operator module implements; each is optional, with the default named. */\nexport interface OperatorPorts {\n /** Allows or refuses an operation for an account. Default: allow. */\n readonly limits?: { check(q: LimitQuery): Promise<LimitAnswer> };\n /** Counters in batches, at least once. Default: discard. */\n readonly metering?: { record(batch: MeterBatch): Promise<void> };\n /**\n * Identity providers beside the configured ones, asked at each sign-in so the set can change\n * while the server runs (WP-30). Default: none.\n */\n readonly identity?: {\n providers(): Promise<readonly IdentityProvider[]> | readonly IdentityProvider[];\n };\n /**\n * Sign-in identities to accounts, a first sign-in step, and credentials the operator issued.\n * Default: the server's own accounts, no step, no outside credential.\n */\n readonly accounts?: {\n resolve(\n identity: SignInIdentity,\n context: { readonly steps: number },\n ): Promise<AccountResolution>;\n authenticate?(\n bearer: string,\n context: { readonly resource: CredentialResource },\n ): Promise<AuthenticatedCredential | null>;\n status?(account: string): Promise<\"active\" | \"suspended\">;\n };\n /** Reports and the after-push hook. Default: nothing. */\n readonly abuse?: {\n report(r: AbuseReport): Promise<void>;\n pushed?(v: PushedVersion): Promise<PushedAnswer>;\n };\n /** Per link and per chat host. Default: nothing beyond configuration. */\n readonly policy?: {\n link(q: LinkQuery): Promise<LinkPolicy>;\n chatHost?(client: {\n readonly name: string;\n readonly redirectHost?: string;\n }): Promise<ChatHostPolicy | null>;\n };\n /**\n * Hosts the operator supplies, and the host a new link is minted on. Default: the server's own\n * labels, and links on the active domain.\n */\n readonly routing?: {\n resolve(host: string): Promise<RoutingAnswer>;\n /**\n * The shell host a new link of this route is minted on (one `resolve` answers `shell` or\n * `route` for), or `null` for the active domain (WP-30). A link keeps the host it was minted\n * on (D137).\n */\n linkHost?(q: {\n readonly account: string;\n readonly home: string;\n readonly routeId: string;\n }): Promise<string | null>;\n };\n /** Outbound events, at least once with stable IDs. Default: discard. */\n readonly events?: { deliver(e: OperatorEvent): Promise<void> };\n /**\n * Invitations to expected respondents (D121, D168): for each respondent a hosted roster names\n * with an `email`, when they are added or their personal link is replaced, so the operator can\n * mail them their link. At least once, ordered per home, with a stable `invitationId`. No mailer\n * ships: the open server only hands them over. Default: none sent.\n */\n readonly invitations?: { send(invitation: Invitation): Promise<void> };\n}\n\n/**\n * One invitation (D168). `url` is the respondent's personal link, a capability URL whose secret is\n * in its fragment: the server never stores or logs it (it builds it from the link's token when it\n * hands the invitation over), so the operator mails it and keeps it no longer than that.\n */\nexport interface Invitation {\n /** Stable across retries: `<home>:<tokenId>`, one per personal link. */\n readonly invitationId: string;\n /** The account that owns the route. */\n readonly account: string;\n /** Its hosted home. */\n readonly home: string;\n /** The route. */\n readonly routeId: string;\n /** The route's label. */\n readonly label: string;\n /** The artifact's ID. */\n readonly artifactId: string;\n /** The artifact's title, as its latest version names it. */\n readonly title: string;\n /** Who is invited: the owner's key for them, their name and the address to write to. */\n readonly respondent: { readonly ref: string; readonly name?: string; readonly email: string };\n /** Who invites: the owner's display name and the provider that verified it, when one did. */\n readonly sender: { readonly name?: string; readonly verifiedBy?: string };\n /** The personal link. */\n readonly url: string;\n /** When the link stops working, when it has a lifetime. */\n readonly expiresAt?: string;\n /** When the respondent was added, or their link replaced. */\n readonly at: string;\n}\n\n/** A hosted route, or one version of it: what the handle's quarantine and release act on. */\nexport type RouteTarget =\n | { readonly routeId: string }\n | { readonly routeId: string; readonly versionId: string };\n\n/**\n * What the server gives its operator module (INTERFACES §18.6). Every target names a hosted route.\n * Each call is durable when it resolves.\n */\nexport interface ServerHandle {\n /** The operator boundary's revision this server speaks. */\n readonly revision: string;\n /** The server's API origin. */\n readonly apiOrigin: string;\n /** A neutral \"under review\" page from the shell; data kept; `release` restores it. */\n quarantine(target: RouteTarget, reason: string): Promise<void>;\n /** Ends a quarantine. */\n release(target: RouteTarget): Promise<void>;\n /** Views keep working; submissions and relayed actions are refused; only the operator resumes. */\n pause(routeId: string, reason: string): Promise<void>;\n /** Ends an operator's pause (and an owner's, too). */\n resume(routeId: string): Promise<void>;\n /** Refuses the home's bindings, pushes, links and pages until `resumeHome`. */\n suspendHome(home: string, reason: string): Promise<void>;\n /** Ends a suspension. */\n resumeHome(home: string): Promise<void>;\n /** Revokes every link of a route; answers how many were live. */\n revokeLinks(routeId: string): Promise<number>;\n /** Revokes one link (410 from then on). */\n revokeLink(tokenId: string): Promise<void>;\n /** Closes the home and refuses to reopen it, to move it between data directories. */\n drainHome(home: string): Promise<void>;\n /** Serves a drained home again. */\n releaseHome(home: string): Promise<void>;\n /** A restore from a backup: rotates the home's incarnation before it serves anything. */\n restored(home: string): Promise<void>;\n /** Deletion: explicit, never part of another action. The route's label is never issued again. */\n remove(routeId: string): Promise<void>;\n}\n\n/** An operator module's default export. */\nexport type OperatorModule = (server: ServerHandle) => OperatorPorts | Promise<OperatorPorts>;\n\n/** Types an operator module's default export; returns it unchanged. */\nexport function defineOperator(module: OperatorModule): OperatorModule {\n return module;\n}\n"],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mostra/protocol",
3
- "version": "0.12.0",
3
+ "version": "0.13.0",
4
4
  "description": "Mostra's shared protocol vocabulary: IDs, dated revisions and diagnostics, with Zod schemas and generated JSON Schema.",
5
5
  "license": "Apache-2.0",
6
6
  "author": "The Mostra Authors",
@@ -79,8 +79,8 @@ export const remoteDiagnostics: AreaCatalog<RemoteDiagnosticCode> = {
79
79
  hint: "Wait for the owner to come back and work through its queue, then press again.",
80
80
  docs: {
81
81
  explanation:
82
- "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.",
83
- 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.",
82
+ "The artifact's owner instance is offline and as many runs as the server allows already wait for it, or the server's operator allows no more waiting runs for this account now (its `limits` port, `run.wait`, whose message is the operator's own), so this one was refused before anything was recorded. Runs already waiting keep their place.",
83
+ 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, or the operator's limit its message names; its `Retry-After`, when present, says when to try again.",
84
84
  },
85
85
  },
86
86
  MOSTRA_REMOTE_NOT_OWNER_INSTANCE: {
package/src/operator.ts CHANGED
@@ -53,8 +53,14 @@ export const OPERATOR_TIME_LIMITS: {
53
53
 
54
54
  /**
55
55
  * An operation `limits.check` judges. When the operator doesn't answer in time, `share`,
56
- * `version.push`, `link` and authoring fail closed, and `view`, `submit` and draft writes proceed,
57
- * so nothing a person typed is lost (D165 item 9).
56
+ * `version.push`, `link` and authoring fail closed, and `view`, `submit`, draft writes and relayed
57
+ * actions (`run`, `run.wait`, `call`) proceed, so nothing a person typed or pressed is lost (D165
58
+ * item 9).
59
+ *
60
+ * - `run`: a relayed action run is about to be recorded (quantity 1). A request that joins a run
61
+ * already recorded (its key or client key) is never asked.
62
+ * - `run.wait`: that run would wait for its owner, who is away (quantity 1), asked after `run`.
63
+ * - `call`: a plain call is about to be relayed to the owner (quantity 1).
58
64
  */
59
65
  export type LimitOperation =
60
66
  | "share"
@@ -78,9 +84,15 @@ export interface LimitQuery {
78
84
  readonly artifact?: string;
79
85
  /** The artifact's hosted route, for operations on one (WP-30). */
80
86
  readonly routeId?: string;
87
+ /**
88
+ * The version being pushed, on `version.push` and `storage` (MT-03): a push that takes several
89
+ * rounds (the owner uploads the files it was told are missing, then pushes again) asks about the
90
+ * same version each round, so an operator counting versions counts this ID once.
91
+ */
92
+ readonly versionId?: string;
81
93
  /** What is asked for. */
82
94
  readonly operation: LimitOperation;
83
- /** How much: bytes for `storage` and `version.push`, else 1. */
95
+ /** How much: bytes for `storage`, else 1. */
84
96
  readonly quantity?: number;
85
97
  }
86
98
 
@@ -118,12 +130,19 @@ export const LimitAnswer: z.ZodType<LimitAnswer> = z.union([
118
130
 
119
131
  // ── metering ────────────────────────────────────────────────────────────────────────────
120
132
 
121
- /** A counter's name (INTERFACES §18.6). */
133
+ /**
134
+ * A counter's name (INTERFACES §18.6). `bytes.stored` sums the client bytes a home uploads in a
135
+ * window; `bytes.held` is a level, not a sum: the client bytes a home holds, each file once however
136
+ * many of its versions name it, sent in the window after it changes (so it falls to what is left,
137
+ * and to 0 once, when content is removed), and for every home holding anything at the first window
138
+ * after a server starts and once a day (MT-03). Keep the latest value per home.
139
+ */
122
140
  export type MeterName =
123
141
  | "views"
124
142
  | "submissions"
125
143
  | "requests"
126
144
  | "bytes.stored"
145
+ | "bytes.held"
127
146
  | "bytes.egress"
128
147
  | "relay.messages"
129
148
  | "mcp.calls"
@@ -170,7 +189,10 @@ export interface MeterBatch {
170
189
 
171
190
  /**
172
191
  * Who an identity provider says signed in (INTERFACES §18.5). `facts` carries what a provider
173
- * tells beyond that (GitHub's account age, `createdAt`), for an operator's policy.
192
+ * tells beyond that, for an operator's policy: the built-in GitHub adapter gives `login`, the
193
+ * account's age (`createdAt`) and its public counts (`publicRepos`, `publicGists`, `followers`, from
194
+ * the same lookup, MT-03); the OpenID Connect adapter gives the ID token's claims its configuration
195
+ * names (`claims`, such as a Google Workspace account's domain `hd`), each under its own name.
174
196
  */
175
197
  export interface SignInIdentity {
176
198
  /** The provider's ID (`IdentityProvider.id`). */
@@ -183,7 +205,7 @@ export interface SignInIdentity {
183
205
  readonly emailVerified?: boolean;
184
206
  /** The display name the provider gives. */
185
207
  readonly name?: string;
186
- /** What else the provider tells (an account's age as `createdAt`). */
208
+ /** What else the provider tells (an account's age as `createdAt`, chosen claims). */
187
209
  readonly facts?: Readonly<Record<string, unknown>>;
188
210
  }
189
211
 
@@ -224,6 +246,15 @@ export interface IdentityProvider {
224
246
  readonly id: string;
225
247
  /** What the sign-in page calls it ("GitHub"). */
226
248
  readonly label: string;
249
+ /**
250
+ * Whether the provider verifies the names it gives, and the label a hosted page's sender line
251
+ * shows for it ("verified with Acme"; 1 to 64 characters, shown as text). Absent: a person who
252
+ * signs in through it is shown "name not verified". The server records the label on the sign-in
253
+ * identity when the provider links or signs in that person, so renaming or retiring the provider
254
+ * later changes no name already verified (MT-03). The built-in providers verify, but for the
255
+ * development one.
256
+ */
257
+ readonly verifies?: { readonly label: string };
227
258
  /** Where to send the person: the provider's authorization URL with `state` and PKCE. */
228
259
  authorize(state: string, pkce: SignInPkce, context: SignInContext): string | Promise<string>;
229
260
  /**
@@ -374,7 +405,10 @@ export interface LinkPolicy extends Cacheable {
374
405
  readonly interstitial?: { readonly kind: string; readonly message?: string };
375
406
  /** The longest a link may live from when it was minted. */
376
407
  readonly maxTtl?: string;
377
- /** A link unused for this long expires. */
408
+ /**
409
+ * A link without a view for this long expires: judged from its last view before the one being
410
+ * opened (or from its minting), so a fresh visit to an idle link is refused as well (MT-03).
411
+ */
378
412
  readonly idleExpiry?: string;
379
413
  /** The line after "Your answer was sent.", as text. */
380
414
  readonly afterSubmit?: string;