@mostra/protocol 0.11.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.
Files changed (97) hide show
  1. package/dist/actions.d.ts +11 -3
  2. package/dist/actions.d.ts.map +1 -1
  3. package/dist/actions.js.map +1 -1
  4. package/dist/browser.d.ts +1 -1
  5. package/dist/diagnostics/codes/index.d.ts +3 -2
  6. package/dist/diagnostics/codes/index.d.ts.map +1 -1
  7. package/dist/diagnostics/codes/index.js +3 -1
  8. package/dist/diagnostics/codes/index.js.map +1 -1
  9. package/dist/diagnostics/codes/remote.js +2 -2
  10. package/dist/diagnostics/codes/remote.js.map +1 -1
  11. package/dist/diagnostics/codes/team.d.ts +8 -0
  12. package/dist/diagnostics/codes/team.d.ts.map +1 -0
  13. package/dist/diagnostics/codes/team.js +44 -0
  14. package/dist/diagnostics/codes/team.js.map +1 -0
  15. package/dist/diagnostics/diagnostic.d.ts +1 -1
  16. package/dist/diagnostics/diagnostic.d.ts.map +1 -1
  17. package/dist/diagnostics/diagnostic.js +2 -1
  18. package/dist/diagnostics/diagnostic.js.map +1 -1
  19. package/dist/index.d.ts +13 -6
  20. package/dist/index.js +11 -4
  21. package/dist/interaction.d.ts +12 -3
  22. package/dist/interaction.d.ts.map +1 -1
  23. package/dist/interaction.js +15 -12
  24. package/dist/interaction.js.map +1 -1
  25. package/dist/manifest.d.ts +3 -0
  26. package/dist/manifest.d.ts.map +1 -1
  27. package/dist/manifest.js +5 -2
  28. package/dist/manifest.js.map +1 -1
  29. package/dist/methods/index.d.ts.map +1 -1
  30. package/dist/methods/index.js +10 -2
  31. package/dist/methods/index.js.map +1 -1
  32. package/dist/methods/port/trusted-controls-policy.d.ts +1 -1
  33. package/dist/methods/results/get.d.ts +3 -1
  34. package/dist/methods/results/get.d.ts.map +1 -1
  35. package/dist/methods/results/get.js +4 -3
  36. package/dist/methods/results/get.js.map +1 -1
  37. package/dist/methods/results/list.d.ts +33 -0
  38. package/dist/methods/results/list.d.ts.map +1 -0
  39. package/dist/methods/results/list.js +35 -0
  40. package/dist/methods/results/list.js.map +1 -0
  41. package/dist/methods/roster/add.d.ts +47 -0
  42. package/dist/methods/roster/add.d.ts.map +1 -0
  43. package/dist/methods/roster/add.js +46 -0
  44. package/dist/methods/roster/add.js.map +1 -0
  45. package/dist/methods/roster/get.d.ts +18 -0
  46. package/dist/methods/roster/get.d.ts.map +1 -0
  47. package/dist/methods/roster/get.js +22 -0
  48. package/dist/methods/roster/get.js.map +1 -0
  49. package/dist/methods/roster/remove.d.ts +28 -0
  50. package/dist/methods/roster/remove.d.ts.map +1 -0
  51. package/dist/methods/roster/remove.js +31 -0
  52. package/dist/methods/roster/remove.js.map +1 -0
  53. package/dist/methods/share/start.d.ts +15 -2
  54. package/dist/methods/share/start.d.ts.map +1 -1
  55. package/dist/methods/share/start.js +5 -1
  56. package/dist/methods/share/start.js.map +1 -1
  57. package/dist/methods/state/get.d.ts +1 -1
  58. package/dist/methods/state/patch.d.ts +1 -1
  59. package/dist/methods/view/url.d.ts +1 -1
  60. package/dist/methods/wait/wait.d.ts +1 -1
  61. package/dist/operator.d.ts +93 -11
  62. package/dist/operator.d.ts.map +1 -1
  63. package/dist/operator.js.map +1 -1
  64. package/dist/team-settings.d.ts +21 -0
  65. package/dist/team-settings.d.ts.map +1 -0
  66. package/dist/team-settings.js +27 -0
  67. package/dist/team-settings.js.map +1 -0
  68. package/dist/team.d.ts +221 -0
  69. package/dist/team.d.ts.map +1 -0
  70. package/dist/team.js +162 -0
  71. package/dist/team.js.map +1 -0
  72. package/dist/verify.d.ts +7 -0
  73. package/dist/verify.d.ts.map +1 -1
  74. package/dist/verify.js.map +1 -1
  75. package/dist/worker.d.ts +1 -1
  76. package/package.json +1 -1
  77. package/schemas/protocol.draft-07.json +802 -79
  78. package/schemas/protocol.schema.json +782 -91
  79. package/src/actions.ts +8 -4
  80. package/src/diagnostics/codes/index.ts +6 -2
  81. package/src/diagnostics/codes/remote.ts +2 -2
  82. package/src/diagnostics/codes/team.ts +53 -0
  83. package/src/diagnostics/diagnostic.ts +3 -1
  84. package/src/index.ts +47 -2
  85. package/src/interaction.ts +24 -5
  86. package/src/manifest.ts +5 -0
  87. package/src/methods/index.ts +8 -0
  88. package/src/methods/results/get.ts +3 -2
  89. package/src/methods/results/list.ts +61 -0
  90. package/src/methods/roster/add.ts +77 -0
  91. package/src/methods/roster/get.ts +30 -0
  92. package/src/methods/roster/remove.ts +49 -0
  93. package/src/methods/share/start.ts +23 -3
  94. package/src/operator.ts +83 -10
  95. package/src/team-settings.ts +38 -0
  96. package/src/team.ts +398 -0
  97. package/src/verify.ts +7 -0
package/src/actions.ts CHANGED
@@ -11,6 +11,7 @@
11
11
  import * as z from "zod";
12
12
  import { ViewId } from "./ids.ts";
13
13
  import type { Frame, WireError } from "./serializer.ts";
14
+ import type { PresenceState, RosterForPage } from "./team.ts";
14
15
  import { wireRegistry } from "./wire-registry.ts";
15
16
 
16
17
  /** A value written by the serializer: its batches, in order (`serializeAll`). */
@@ -270,13 +271,16 @@ export interface LiveUpdate {
270
271
  }
271
272
 
272
273
  /**
273
- * An ephemeral message on a page's event stream (SSE `event: run` or `event: live`, without an
274
- * `id`, so a reconnect's cursor is untouched) or in a poll's `ephemeral`: lossy, coalesced, and
275
- * never stored as an event.
274
+ * An ephemeral message on a page's event stream (SSE `event: run`, `live`, `respondents` or
275
+ * `presence`, without an `id`, so a reconnect's cursor is untouched) or in a poll's `ephemeral`:
276
+ * lossy, coalesced, and never stored as an event. `respondents` and `presence` (D168) reach only a
277
+ * page that asked for them, so a version built before them never receives one.
276
278
  */
277
279
  export type EphemeralMessage =
278
280
  | { readonly kind: "run"; readonly run: RunDelta }
279
- | { readonly kind: "live"; readonly live: LiveUpdate };
281
+ | { readonly kind: "live"; readonly live: LiveUpdate }
282
+ | { readonly kind: "respondents"; readonly respondents: RosterForPage }
283
+ | { readonly kind: "presence"; readonly presence: PresenceState };
280
284
 
281
285
  /** `POST …/call/{fnId}`: a plain server-function call, no durable record (D54). */
282
286
  export interface CallRequest {
@@ -22,7 +22,6 @@ import { type NetworkDiagnosticCode, networkDiagnostics } from "./network.ts";
22
22
  import { type PlatformDiagnosticCode, platformDiagnostics } from "./platform.ts";
23
23
  import { type PublishDiagnosticCode, publishDiagnostics } from "./publish.ts";
24
24
  import { type RegressionDiagnosticCode, regressionDiagnostics } from "./regression.ts";
25
- // gen:area-imports
26
25
  import { type RemoteDiagnosticCode, remoteDiagnostics } from "./remote.ts";
27
26
  import { type RuntimeDiagnosticCode, runtimeDiagnostics } from "./runtime.ts";
28
27
  import { type SecretDiagnosticCode, secretDiagnostics } from "./secret.ts";
@@ -30,6 +29,8 @@ import { type ShareDiagnosticCode, shareDiagnostics } from "./share.ts";
30
29
  import { type SmokeDiagnosticCode, smokeDiagnostics } from "./smoke.ts";
31
30
  import { type SubmitDiagnosticCode, submitDiagnostics } from "./submit.ts";
32
31
  import { type TargetDiagnosticCode, targetDiagnostics } from "./target.ts";
32
+ // gen:area-imports
33
+ import { type TeamDiagnosticCode, teamDiagnostics } from "./team.ts";
33
34
  import { type TypeDiagnosticCode, typeDiagnostics } from "./type.ts";
34
35
  import { type VerifyDiagnosticCode, verifyDiagnostics } from "./verify.ts";
35
36
 
@@ -51,7 +52,6 @@ export { type NetworkDiagnosticCode, networkDiagnosticCodes } from "./network.ts
51
52
  export { type PlatformDiagnosticCode, platformDiagnosticCodes } from "./platform.ts";
52
53
  export { type PublishDiagnosticCode, publishDiagnosticCodes } from "./publish.ts";
53
54
  export { type RegressionDiagnosticCode, regressionDiagnosticCodes } from "./regression.ts";
54
- // gen:area-exports
55
55
  export { type RemoteDiagnosticCode, remoteDiagnosticCodes } from "./remote.ts";
56
56
  export { type RuntimeDiagnosticCode, runtimeDiagnosticCodes } from "./runtime.ts";
57
57
  export { type SecretDiagnosticCode, secretDiagnosticCodes } from "./secret.ts";
@@ -59,12 +59,15 @@ export { type ShareDiagnosticCode, shareDiagnosticCodes } from "./share.ts";
59
59
  export { type SmokeDiagnosticCode, smokeDiagnosticCodes } from "./smoke.ts";
60
60
  export { type SubmitDiagnosticCode, submitDiagnosticCodes } from "./submit.ts";
61
61
  export { type TargetDiagnosticCode, targetDiagnosticCodes } from "./target.ts";
62
+ // gen:area-exports
63
+ export { type TeamDiagnosticCode, teamDiagnosticCodes } from "./team.ts";
62
64
  export { type TypeDiagnosticCode, typeDiagnosticCodes } from "./type.ts";
63
65
  export { type VerifyDiagnosticCode, verifyDiagnosticCodes } from "./verify.ts";
64
66
 
65
67
  /** Every code in the catalog. Codes are semver surface and are never removed (AX-03). */
66
68
  export type KnownDiagnosticCode =
67
69
  // gen:area-codes
70
+ | TeamDiagnosticCode
68
71
  | RemoteDiagnosticCode
69
72
  | ShareDiagnosticCode
70
73
  | CliDiagnosticCode
@@ -96,6 +99,7 @@ export type KnownDiagnosticCode =
96
99
  /** Every cataloged code with its severity, phase, title, default hint and docs text. */
97
100
  export const diagnosticCatalog: Readonly<Record<KnownDiagnosticCode, DiagnosticSpec>> = {
98
101
  // gen:area-spreads
102
+ ...teamDiagnostics,
99
103
  ...remoteDiagnostics,
100
104
  ...shareDiagnostics,
101
105
  ...cliDiagnostics,
@@ -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: {
@@ -0,0 +1,53 @@
1
+ /**
2
+ * Diagnostic codes of the TEAM area.
3
+ */
4
+ import type { AreaCatalog } from "../spec.ts";
5
+
6
+ /** The codes of the TEAM area, in the order they were added. */
7
+ export const teamDiagnosticCodes = [
8
+ "MOSTRA_TEAM_ROSTER_POLICY",
9
+ "MOSTRA_TEAM_ROSTER_TOO_LARGE",
10
+ "MOSTRA_TEAM_PRESENCE_RATE_LIMITED",
11
+ // gen:codes
12
+ ] as const;
13
+
14
+ /** The codes of the TEAM area. */
15
+ export type TeamDiagnosticCode = (typeof teamDiagnosticCodes)[number];
16
+
17
+ /** The TEAM area's catalog entries. */
18
+ export const teamDiagnostics: AreaCatalog<TeamDiagnosticCode> = {
19
+ MOSTRA_TEAM_ROSTER_POLICY: {
20
+ severity: "error",
21
+ phase: "host",
22
+ title: "This artifact's policy can't wait for every respondent",
23
+ hint: "Publish with the submission policy once per-viewer or epochs, then wait again; or wait for submitted.",
24
+ docs: {
25
+ explanation:
26
+ "`submitted:all` waits until every expected respondent has submitted, and `submitted:<N>` for N submissions. Both need a policy that takes a submission from each person: `once` with scope `per-viewer`, or `epochs`. Under `once` per-artifact the artifact takes one submission in all, so neither can be met beyond the first, and Mostra refuses the wait instead of letting it run forever.",
27
+ fix: "Publish again with `mostra publish <path> --policy once-per-viewer` (or `--policy epochs`), or wait for `submitted`.",
28
+ },
29
+ },
30
+ MOSTRA_TEAM_ROSTER_TOO_LARGE: {
31
+ severity: "error",
32
+ phase: "host",
33
+ title: "Roster larger than 1,000 respondents",
34
+ hint: "Name at most 1,000 expected respondents; share one link for everyone else instead.",
35
+ docs: {
36
+ explanation:
37
+ "A roster lists the people an artifact expects answers from, each with a personal link and a status. It holds at most 1,000 of them. Nothing was added: the roster is as it was.",
38
+ fix: "Remove respondents you no longer expect (`mostra roster remove`), or, for a page many people answer, share one link and wait for `submitted:<N>` instead.",
39
+ },
40
+ },
41
+ MOSTRA_TEAM_PRESENCE_RATE_LIMITED: {
42
+ severity: "error",
43
+ phase: "hygiene",
44
+ title: "Presence updates too fast",
45
+ hint: "Send presence at most 10 times a second; usePresence does this for you.",
46
+ docs: {
47
+ explanation:
48
+ "A page shares its viewer's cursor and selection through `POST /_mostra/v/<rev>/presence`. Each view may send 20 updates a second; past that the gateway answers 429 with `Retry-After`. Presence is never stored, so nothing is lost: the next update replaces the last one.",
49
+ fix: "Use `usePresence` from `@mostra/react`, which sends at most 10 updates a second, or throttle your own calls to the route.",
50
+ },
51
+ },
52
+ // gen:entries
53
+ };
@@ -40,7 +40,8 @@ export type DiagnosticArea =
40
40
  | "PLATFORM"
41
41
  | "ARTIFACT"
42
42
  | "CLI"
43
- | "REMOTE";
43
+ | "REMOTE"
44
+ | "TEAM";
44
45
 
45
46
  /** Every diagnostic area, in INTERFACES §13 order. */
46
47
  export const DIAGNOSTIC_AREAS: readonly DiagnosticArea[] = [
@@ -75,6 +76,7 @@ export const DIAGNOSTIC_AREAS: readonly DiagnosticArea[] = [
75
76
  "ARTIFACT",
76
77
  "CLI",
77
78
  "REMOTE",
79
+ "TEAM",
78
80
  ];
79
81
 
80
82
  /**
package/src/index.ts CHANGED
@@ -195,8 +195,10 @@ export {
195
195
  smokeDiagnosticCodes,
196
196
  submitDiagnosticCodes,
197
197
  type TargetDiagnosticCode,
198
+ type TeamDiagnosticCode,
198
199
  type TypeDiagnosticCode,
199
200
  targetDiagnosticCodes,
201
+ teamDiagnosticCodes,
200
202
  typeDiagnosticCodes,
201
203
  type VerifyDiagnosticCode,
202
204
  verifyDiagnosticCodes,
@@ -283,7 +285,7 @@ export {
283
285
  SubmitChannel,
284
286
  TrustedControl,
285
287
  Viewer,
286
- type ViewerKind,
288
+ ViewerKind,
287
289
  ViewerSpec,
288
290
  type Viewport,
289
291
  WaitCondition,
@@ -577,10 +579,32 @@ export {
577
579
  } from "./methods/remote/token.ts";
578
580
  export {
579
581
  type ResultsGetParams,
580
- type ResultsGetResult,
582
+ ResultsGetResult,
581
583
  ResultsMarkdown,
582
584
  resultsGetMethod,
583
585
  } from "./methods/results/get.ts";
586
+ export {
587
+ RESULTS_LIST_MAX,
588
+ type ResultsListParams,
589
+ type ResultsListResult,
590
+ resultsListMethod,
591
+ } from "./methods/results/list.ts";
592
+ export {
593
+ RespondentLink,
594
+ type RosterAddParams,
595
+ type RosterAddResult,
596
+ rosterAddMethod,
597
+ } from "./methods/roster/add.ts";
598
+ export {
599
+ type RosterGetParams,
600
+ type RosterGetResult,
601
+ rosterGetMethod,
602
+ } from "./methods/roster/get.ts";
603
+ export {
604
+ type RosterRemoveParams,
605
+ type RosterRemoveResult,
606
+ rosterRemoveMethod,
607
+ } from "./methods/roster/remove.ts";
584
608
  export {
585
609
  type SecretDeleteParams,
586
610
  type SecretDeleteResult,
@@ -710,6 +734,27 @@ export {
710
734
  type WireError,
711
735
  wireError,
712
736
  } from "./serializer.ts";
737
+ export {
738
+ DEFAULT_TEAM_VISIBILITY,
739
+ type Peer,
740
+ PRESENCE_COORDINATE_MAX,
741
+ PresenceCursor,
742
+ PresencePeer,
743
+ PresenceRequest,
744
+ PresenceSelection,
745
+ PresenceState,
746
+ Respondent,
747
+ RespondentForPage,
748
+ RespondentSpec,
749
+ RespondentStatus,
750
+ RespondentsRequest,
751
+ ROSTER_MAX,
752
+ Roster,
753
+ RosterCounts,
754
+ RosterForPage,
755
+ TeamSettings,
756
+ TeamVisibility,
757
+ } from "./team.ts";
713
758
  export {
714
759
  ARTIFACT_PROGRESS,
715
760
  ArtifactProgressParams,
@@ -29,6 +29,16 @@ export { ControlsPolicy, SubmitChannel, TrustedControl } from "./view.ts";
29
29
  */
30
30
  export type ViewerKind = "local" | "tailnet" | "token" | "host" | "account" | "anonymous";
31
31
 
32
+ /** The Zod schema of the `ViewerKind` type (inlined where it is used, never a definition of its own). */
33
+ export const ViewerKind: z.ZodType<ViewerKind> = z.enum([
34
+ "local",
35
+ "tailnet",
36
+ "token",
37
+ "host",
38
+ "account",
39
+ "anonymous",
40
+ ]);
41
+
32
42
  /**
33
43
  * A person who views an artifact (PRODUCT vocabulary). The home's local user is one viewer of kind
34
44
  * `local`; a link minted with `viewer` acts as a viewer of kind `token` (D104).
@@ -53,7 +63,7 @@ export interface Viewer {
53
63
  export const Viewer: z.ZodType<Viewer> = z
54
64
  .object({
55
65
  id: ViewerId.schema,
56
- kind: z.enum(["local", "tailnet", "token", "host", "account", "anonymous"]),
66
+ kind: ViewerKind,
57
67
  name: z.string().exactOptional(),
58
68
  ref: z.string().exactOptional(),
59
69
  verified: z.boolean().exactOptional(),
@@ -93,6 +103,12 @@ export interface Actor {
93
103
  readonly id?: string;
94
104
  /** A display name, when one is known. */
95
105
  readonly name?: string;
106
+ /**
107
+ * For a viewer, as a page sees another one (D168): an opaque key, stable for that viewer of this
108
+ * artifact, never their viewer ID (D104), so attribution, respondents and presence name one person
109
+ * alike.
110
+ */
111
+ readonly key?: string;
96
112
  }
97
113
 
98
114
  /** The Zod schema of the `Actor` type. */
@@ -101,6 +117,7 @@ export const Actor: z.ZodType<Actor> = z
101
117
  kind: z.enum(["viewer", "agent", "host", "mostra"]),
102
118
  id: z.string().exactOptional(),
103
119
  name: z.string().exactOptional(),
120
+ key: z.string().exactOptional(),
104
121
  })
105
122
  .register(wireRegistry, {
106
123
  id: "Actor",
@@ -387,8 +404,9 @@ export const EventFilter: z.ZodType<EventFilter> = z
387
404
  });
388
405
 
389
406
  /**
390
- * What `wait` waits for (ARCHITECTURE §6, D103): `submitted`, `signal:<name>`, `state:<fieldId>`
391
- * or `event:<type pattern>`.
407
+ * What `wait` waits for (ARCHITECTURE §6, D103, D168): `submitted`, `submitted:all` (every expected
408
+ * respondent submitted: the roster completed), `submitted:<N>` (N submissions, 1 to 10,000),
409
+ * `signal:<name>`, `state:<fieldId>` or `event:<type pattern>`.
392
410
  */
393
411
  export type WaitCondition = string;
394
412
 
@@ -400,11 +418,12 @@ export const WaitCondition: z.ZodType<WaitCondition> = z
400
418
  .string()
401
419
  .regex(
402
420
  // biome-ignore lint/suspicious/noControlCharactersInRegex: field IDs exclude control characters.
403
- /^(submitted|signal:[A-Za-z0-9][A-Za-z0-9._-]{0,63}|state:[^\u0000-\u001f\u007f]{1,256}|event:[a-z][a-zA-Z0-9_-]*(\.[a-zA-Z0-9_-]+)*(\.\*)?)$/,
421
+ /^(?:(submitted|signal:[A-Za-z0-9][A-Za-z0-9._-]{0,63}|state:[^\u0000-\u001f\u007f]{1,256}|event:[a-z][a-zA-Z0-9_-]*(\.[a-zA-Z0-9_-]+)*(\.\*)?)$|submitted:(?:all|[1-9][0-9]{0,3}|10000)$)/,
404
422
  )
405
423
  .register(wireRegistry, {
406
424
  id: "WaitCondition",
407
- description: "What wait waits for: submitted, signal:<name>, state:<fieldId> or event:<type>.",
425
+ description:
426
+ "What wait waits for: submitted, submitted:all, submitted:<N>, signal:<name>, state:<fieldId> or event:<type>.",
408
427
  });
409
428
 
410
429
  // ── Submissions, deliveries and results ──────────────────────────────────────────────────
package/src/manifest.ts CHANGED
@@ -15,6 +15,7 @@ import { SubmissionPolicy } from "./policy.ts";
15
15
  export { SubmissionPolicy };
16
16
 
17
17
  import { ArtifactId } from "./ids.ts";
18
+ import { TeamSettings } from "./team-settings.ts";
18
19
  import { wireRegistry } from "./wire-registry.ts";
19
20
 
20
21
  /** The families Mostra's templates and gallery know; any other string is allowed too. */
@@ -144,6 +145,8 @@ export interface ArtifactManifest {
144
145
  readonly tally?: readonly TallySpec[];
145
146
  /** How the artifact behaves on a remote server (D165). */
146
147
  readonly hosted?: HostedSettings;
148
+ /** Team settings: what viewers see of each other's status and presence (D168). */
149
+ readonly team?: TeamSettings;
147
150
  }
148
151
 
149
152
  /** The keys of the artifact manifest, in INTERFACES §2.2 order. Other keys are warnings (FAILURE_MODEL §10). */
@@ -162,6 +165,7 @@ export const ARTIFACT_MANIFEST_KEYS: readonly (keyof ArtifactManifest)[] = [
162
165
  "verify",
163
166
  "tally",
164
167
  "hosted",
168
+ "team",
165
169
  ];
166
170
 
167
171
  const strings = z.array(z.string()).readonly();
@@ -264,6 +268,7 @@ export const ArtifactManifest: z.ZodType<ArtifactManifest> = z
264
268
  .exactOptional(),
265
269
  tally: z.array(TallySpec).readonly().exactOptional(),
266
270
  hosted: HostedSettings.exactOptional(),
271
+ team: TeamSettings.exactOptional(),
267
272
  })
268
273
  .register(wireRegistry, {
269
274
  id: "ArtifactManifest",
@@ -51,6 +51,10 @@ import { remoteLogoutMethod } from "./remote/logout.ts";
51
51
  import { remoteStatusMethod } from "./remote/status.ts";
52
52
  import { remoteTokenMethod } from "./remote/token.ts";
53
53
  import { resultsGetMethod } from "./results/get.ts";
54
+ import { resultsListMethod } from "./results/list.ts";
55
+ import { rosterAddMethod } from "./roster/add.ts";
56
+ import { rosterGetMethod } from "./roster/get.ts";
57
+ import { rosterRemoveMethod } from "./roster/remove.ts";
54
58
  import { secretDeleteMethod } from "./secret/delete.ts";
55
59
  import { secretListMethod } from "./secret/list.ts";
56
60
  import { secretSetMethod } from "./secret/set.ts";
@@ -130,6 +134,10 @@ export const hostMethods: readonly AnyMethod[] = [
130
134
  artifactPauseMethod,
131
135
  portRelayAuthorMethod,
132
136
  remoteLinkMethod,
137
+ rosterAddMethod,
138
+ rosterRemoveMethod,
139
+ rosterGetMethod,
140
+ resultsListMethod,
133
141
  // gen:methods
134
142
  ];
135
143
 
@@ -42,7 +42,8 @@ export const ResultsMarkdown: z.ZodType<ResultsMarkdown> = z
42
42
  description: "A submission's results as Markdown for agents.",
43
43
  });
44
44
 
45
- const result: z.ZodType<ResultsGetResult> = z
45
+ /** The Zod schema of the `ResultsGetResult` type. */
46
+ export const ResultsGetResult: z.ZodType<ResultsGetResult> = z
46
47
  .union([Results, ResultsMarkdown])
47
48
  .register(wireRegistry, { id: "ResultsGetResult" });
48
49
 
@@ -55,5 +56,5 @@ export const resultsGetMethod: MethodDefinition<ResultsGetParams, ResultsGetResu
55
56
  direction: "client-to-instance",
56
57
  mutating: false,
57
58
  params,
58
- result,
59
+ result: ResultsGetResult,
59
60
  });
@@ -0,0 +1,61 @@
1
+ import * as z from "zod";
2
+ import { ArtifactRef } from "../../artifact.ts";
3
+ import { Cursor } from "../../ids.ts";
4
+ import { defineMethod, type MethodDefinition } from "../../method.ts";
5
+ import { wireRegistry } from "../../wire-registry.ts";
6
+ import { type ResultsGetResult, ResultsGetResult as ResultsGetResultSchema } from "./get.ts";
7
+
8
+ /** The most submissions one `results/list` answer carries. */
9
+ export const RESULTS_LIST_MAX = 100;
10
+
11
+ /** The params of `results/list` (INTERFACES §6, §8, D168). */
12
+ export interface ResultsListParams {
13
+ /** The artifact whose submissions to read. */
14
+ readonly artifact: ArtifactRef;
15
+ /** Only submissions made after this cursor; absent: from the first. */
16
+ readonly after?: string;
17
+ /** At most this many, oldest first (1 to 100, default 100). */
18
+ readonly limit?: number;
19
+ /** `json` (the default): the Results structure of each; `md`: each as Markdown. */
20
+ readonly format?: "json" | "md";
21
+ }
22
+
23
+ /** The result of `results/list`. */
24
+ export interface ResultsListResult {
25
+ /** The submissions, oldest first, each as `results/get` gives it. */
26
+ readonly results: readonly ResultsGetResult[];
27
+ /** The cursor to read on from: the last submission's, or `after` when none came. */
28
+ readonly cursor: string;
29
+ /** Whether more submissions follow the cursor. */
30
+ readonly more: boolean;
31
+ }
32
+
33
+ const params: z.ZodType<ResultsListParams> = z
34
+ .object({
35
+ artifact: ArtifactRef,
36
+ after: Cursor.schema.exactOptional(),
37
+ limit: z.int().min(1).max(RESULTS_LIST_MAX).exactOptional(),
38
+ format: z.enum(["json", "md"]).exactOptional(),
39
+ })
40
+ .register(wireRegistry, { id: "ResultsListParams" });
41
+
42
+ const result: z.ZodType<ResultsListResult> = z
43
+ .object({
44
+ results: z.array(ResultsGetResultSchema).readonly(),
45
+ cursor: Cursor.schema,
46
+ more: z.boolean(),
47
+ })
48
+ .register(wireRegistry, { id: "ResultsListResult" });
49
+
50
+ /**
51
+ * `results/list`: every submission of an artifact after a cursor, oldest first, as `results/get`
52
+ * gives each (J14: all five answers once the roster completed). Page on with `cursor` while `more`.
53
+ */
54
+ export const resultsListMethod: MethodDefinition<ResultsListParams, ResultsListResult> =
55
+ defineMethod({
56
+ method: "results/list",
57
+ direction: "client-to-instance",
58
+ mutating: false,
59
+ params,
60
+ result,
61
+ });
@@ -0,0 +1,77 @@
1
+ import * as z from "zod";
2
+ import { ArtifactRef } from "../../artifact.ts";
3
+ import { CapabilityScope } from "../../capability.ts";
4
+ import { Duration } from "../../duration.ts";
5
+ import { VersionId } from "../../ids.ts";
6
+ import { defineMethod, type MethodDefinition } from "../../method.ts";
7
+ import { RespondentSpec, ROSTER_MAX, Roster } from "../../team.ts";
8
+ import { wireRegistry } from "../../wire-registry.ts";
9
+ import { CapabilityLink } from "../view/url.ts";
10
+
11
+ /** The params of `roster/add` (INTERFACES §6, D121, D168). */
12
+ export interface RosterAddParams {
13
+ /** The artifact the people are expected to answer. */
14
+ readonly artifact: ArtifactRef;
15
+ /** The people expected to answer, by the host's stable key (D104); one already there is kept. */
16
+ readonly respondents: readonly RespondentSpec[];
17
+ /** What a new personal link allows (D97). Default: every scope. */
18
+ readonly scopes?: readonly CapabilityScope[];
19
+ /** How long a new personal link works. Default: until it is revoked (D63). */
20
+ readonly ttl?: Duration;
21
+ /** The version a new personal link opens, by number or ID; absent: the latest, always. */
22
+ readonly version?: number | string;
23
+ /** Makes retries idempotent (H-03). */
24
+ readonly requestId?: string;
25
+ }
26
+
27
+ /** A respondent's personal link (CO-01). */
28
+ export interface RespondentLink {
29
+ /** The respondent it is for. */
30
+ readonly ref: string;
31
+ /** Their link: it acts as their viewer (D104). Holding it is the authorization (D06). */
32
+ readonly link: CapabilityLink;
33
+ }
34
+
35
+ /** The Zod schema of the `RespondentLink` type. */
36
+ export const RespondentLink: z.ZodType<RespondentLink> = z
37
+ .object({ ref: z.string(), link: CapabilityLink })
38
+ .register(wireRegistry, {
39
+ id: "RespondentLink",
40
+ description: "An expected respondent's personal link, acting as their viewer.",
41
+ });
42
+
43
+ /** The result of `roster/add`. */
44
+ export interface RosterAddResult {
45
+ /** The roster after the change. */
46
+ readonly roster: Roster;
47
+ /** The personal link of every respondent named, in the order given. */
48
+ readonly links: readonly RespondentLink[];
49
+ }
50
+
51
+ const params: z.ZodType<RosterAddParams> = z
52
+ .object({
53
+ artifact: ArtifactRef,
54
+ respondents: z.array(RespondentSpec).min(1).max(ROSTER_MAX).readonly(),
55
+ scopes: z.array(CapabilityScope).min(1).readonly().exactOptional(),
56
+ ttl: Duration.exactOptional(),
57
+ version: z.union([z.int().min(1), VersionId.schema]).exactOptional(),
58
+ requestId: z.string().min(1).exactOptional(),
59
+ })
60
+ .register(wireRegistry, { id: "RosterAddParams" });
61
+
62
+ const result: z.ZodType<RosterAddResult> = z
63
+ .object({ roster: Roster, links: z.array(RespondentLink).readonly() })
64
+ .register(wireRegistry, { id: "RosterAddResult" });
65
+
66
+ /**
67
+ * `roster/add`: names people an artifact expects answers from and gives each a personal link that
68
+ * acts as their viewer (CO-01). Idempotent by `ref`: a respondent already there keeps their link
69
+ * (a revoked one is replaced), and a name given again replaces theirs. Appends `roster.changed`.
70
+ */
71
+ export const rosterAddMethod: MethodDefinition<RosterAddParams, RosterAddResult> = defineMethod({
72
+ method: "roster/add",
73
+ direction: "client-to-instance",
74
+ mutating: true,
75
+ params,
76
+ result,
77
+ });
@@ -0,0 +1,30 @@
1
+ import * as z from "zod";
2
+ import { ArtifactRef } from "../../artifact.ts";
3
+ import { defineMethod, type MethodDefinition } from "../../method.ts";
4
+ import { Roster } from "../../team.ts";
5
+ import { wireRegistry } from "../../wire-registry.ts";
6
+
7
+ /** The params of `roster/get` (INTERFACES §6, D168). */
8
+ export interface RosterGetParams {
9
+ /** The artifact. */
10
+ readonly artifact: ArtifactRef;
11
+ }
12
+
13
+ /** The result of `roster/get`: the whole roster, whatever the visibility policy (CO-07). */
14
+ export type RosterGetResult = Roster;
15
+
16
+ const params: z.ZodType<RosterGetParams> = z
17
+ .object({ artifact: ArtifactRef })
18
+ .register(wireRegistry, { id: "RosterGetParams" });
19
+
20
+ /**
21
+ * `roster/get`: every expected respondent with their status in the current round (CO-03), the
22
+ * round, whether it is complete and its counts. Agents and hosts always read all of it (CO-07).
23
+ */
24
+ export const rosterGetMethod: MethodDefinition<RosterGetParams, RosterGetResult> = defineMethod({
25
+ method: "roster/get",
26
+ direction: "client-to-instance",
27
+ mutating: false,
28
+ params,
29
+ result: Roster,
30
+ });
@@ -0,0 +1,49 @@
1
+ import * as z from "zod";
2
+ import { ArtifactRef } from "../../artifact.ts";
3
+ import { defineMethod, type MethodDefinition } from "../../method.ts";
4
+ import { ROSTER_MAX, Roster } from "../../team.ts";
5
+ import { wireRegistry } from "../../wire-registry.ts";
6
+
7
+ /** The params of `roster/remove` (INTERFACES §6, D168). */
8
+ export interface RosterRemoveParams {
9
+ /** The artifact. */
10
+ readonly artifact: ArtifactRef;
11
+ /** The respondents no longer expected, by `ref`; unknown ones are ignored. */
12
+ readonly refs: readonly string[];
13
+ /** Makes retries idempotent (H-03). */
14
+ readonly requestId?: string;
15
+ }
16
+
17
+ /** The result of `roster/remove`. */
18
+ export interface RosterRemoveResult {
19
+ /** The roster after the change. */
20
+ readonly roster: Roster;
21
+ /** The refs that were on the roster and left it. */
22
+ readonly removed: readonly string[];
23
+ }
24
+
25
+ const params: z.ZodType<RosterRemoveParams> = z
26
+ .object({
27
+ artifact: ArtifactRef,
28
+ refs: z.array(z.string().min(1).max(256)).min(1).max(ROSTER_MAX).readonly(),
29
+ requestId: z.string().min(1).exactOptional(),
30
+ })
31
+ .register(wireRegistry, { id: "RosterRemoveParams" });
32
+
33
+ const result: z.ZodType<RosterRemoveResult> = z
34
+ .object({ roster: Roster, removed: z.array(z.string()).readonly() })
35
+ .register(wireRegistry, { id: "RosterRemoveResult" });
36
+
37
+ /**
38
+ * `roster/remove`: stops expecting answers from people (D168). Their personal links keep working
39
+ * until revoked (`view/revoke`), and their drafts and submissions stay. Appends `roster.changed`,
40
+ * and `roster.completed` when everyone still expected has answered.
41
+ */
42
+ export const rosterRemoveMethod: MethodDefinition<RosterRemoveParams, RosterRemoveResult> =
43
+ defineMethod({
44
+ method: "roster/remove",
45
+ direction: "client-to-instance",
46
+ mutating: true,
47
+ params,
48
+ result,
49
+ });
@@ -5,7 +5,9 @@ import { Duration } from "../../duration.ts";
5
5
  import { ArtifactId, ShareId, TokenId } from "../../ids.ts";
6
6
  import { ViewerSpec } from "../../interaction.ts";
7
7
  import { defineMethod, type MethodDefinition } from "../../method.ts";
8
+ import { RespondentSpec, ROSTER_MAX } from "../../team.ts";
8
9
  import { wireRegistry } from "../../wire-registry.ts";
10
+ import { RespondentLink } from "../roster/add.ts";
9
11
 
10
12
  /**
11
13
  * How a share reaches its viewers (D158): `tailnet` through Tailscale Serve, to the people of the
@@ -49,6 +51,13 @@ export interface ShareStartParams {
49
51
  * port names, else the link's own viewer, never the home's local user (D158).
50
52
  */
51
53
  readonly viewer?: ViewerSpec;
54
+ /**
55
+ * People the artifact expects answers from through this share (D121, D168): they join the
56
+ * roster of the home that holds the artifact's viewers (a remote share's hosted home), and each
57
+ * gets a personal link at the share's address. On a remote server, `email` reaches the operator's
58
+ * `invitations` port. Not with `viewer`.
59
+ */
60
+ readonly respondents?: readonly RespondentSpec[];
52
61
  /** Makes retries idempotent: a repeated `requestId` returns the same share (H-03). */
53
62
  readonly requestId?: string;
54
63
  }
@@ -118,8 +127,14 @@ export const Share: z.ZodType<Share> = z.object(shareShape).register(wireRegistr
118
127
  description: "A share: its tunnel, link, address, frame mode and lifetime.",
119
128
  });
120
129
 
121
- /** The result of `share/start`: the share, with its link. */
122
- export type ShareStartResult = Share & { readonly url: string };
130
+ /**
131
+ * The result of `share/start`: the share, with its link, and the personal link of every respondent
132
+ * it named (D168).
133
+ */
134
+ export type ShareStartResult = Share & {
135
+ readonly url: string;
136
+ readonly respondents?: readonly RespondentLink[];
137
+ };
123
138
 
124
139
  const params: z.ZodType<ShareStartParams> = z
125
140
  .object({
@@ -132,12 +147,17 @@ const params: z.ZodType<ShareStartParams> = z
132
147
  ttl: Duration.exactOptional(),
133
148
  scopes: z.array(CapabilityScope).min(1).readonly().exactOptional(),
134
149
  viewer: ViewerSpec.exactOptional(),
150
+ respondents: z.array(RespondentSpec).min(1).max(ROSTER_MAX).readonly().exactOptional(),
135
151
  requestId: z.string().min(1).exactOptional(),
136
152
  })
137
153
  .register(wireRegistry, { id: "ShareStartParams" });
138
154
 
139
155
  const result: z.ZodType<ShareStartResult> = z
140
- .object({ ...shareShape, url: z.string().min(1) })
156
+ .object({
157
+ ...shareShape,
158
+ url: z.string().min(1),
159
+ respondents: z.array(RespondentLink).readonly().exactOptional(),
160
+ })
141
161
  .register(wireRegistry, {
142
162
  id: "ShareStartResult",
143
163
  description: "The share that started, with its capability URL.",