feat(documents): a document can say which visit it belongs to

Every arm here is the same shape as the one that already exists for
conditions, because the vault's filing model is settled and a second shape
would be the thing to explain rather than the thing to use: encounterIds on
upload and on PATCH with replace-set semantics, linkEncounter / unlinkEncounter
beside the episode pair in the bulk action, and an encounterId list filter.

Both directions ride ONE table. The visit's sheet writes encounter_document_links
from its end and the document reads it from the other, declared as a second
direction in the link service rather than a fourth table. A visit's kind
crosses the wire as the enum constant rather than a rendered name: unlike a
condition label, which is the person's own words, a kind is one of eight closed
values whose human name the reader's own bundle owns.

The suggestion is offered where the document is being looked at, resolved by
the shared rule rather than by this surface: one candidate pre-selects with an
undo, two offer a picker with nothing pre-selected, none offers nothing at all.
It resolves with no AI provider configured, and it renders nothing once the
document already names a visit.

The bulk verb has a caller — the vault's selection bar files a whole selection
against a visit, mirroring the condition verb and hiding itself on an account
with no visits. Nothing here is one-ended.

OpenAPI regenerated in the same commit.

docs/api/openapi.yaml

@@ -11427,6 +11427,12 @@ paths:
           schema:
             type: string
           description: Only documents linked to this illness/condition episode.
+        - name: encounterId
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Only documents linked to this visit.
         - name: year
           in: query
           required: false
@@ -11545,6 +11551,12 @@ paths:
                   type: array
                   items:
                     type: string
+                encounterIds:
+                  description: Optional visit pre-links (repeat the field per id). Every id must be a live visit of the caller; an unknown
+                    one refuses the upload rather than dropping the link the person asked for.
+                  type: array
+                  items:
+                    type: string
               required:
                 - file
       responses:
@@ -11648,6 +11660,8 @@ paths:
                     - setKind
                     - linkEpisode
                     - unlinkEpisode
+                    - linkEncounter
+                    - unlinkEncounter
                     - delete
                     - restore
                 kind:
@@ -11666,6 +11680,10 @@ paths:
                   type: string
                   minLength: 1
                   maxLength: 40
+                encounterId:
+                  type: string
+                  minLength: 1
+                  maxLength: 40
               required:
                 - ids
                 - action
@@ -11750,6 +11768,13 @@ paths:
                     type: string
                     minLength: 1
                     maxLength: 40
+                encounterIds:
+                  maxItems: 20
+                  type: array
+                  items:
+                    type: string
+                    minLength: 1
+                    maxLength: 40
       responses:
         "200":
           description: The updated document.
@@ -36481,6 +36506,10 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/DocumentConditionLink"
+        encounterLinks:
+          type: array
+          items:
+            $ref: "#/components/schemas/DocumentEncounterLink"
         servingClass:
           type: string
           enum:
@@ -36518,6 +36547,7 @@ components:
         - factCount
         - pendingCount
         - conditionLinks
+        - encounterLinks
         - servingClass
         - hasContentIndex
         - contentIndexSource
@@ -36547,6 +36577,26 @@ components:
         - name
       additionalProperties: false
       description: A link to one of the caller's illness/condition episodes. `name` is the episode's user-facing label.
+    DocumentEncounterLink:
+      type: object
+      properties:
+        encounterId:
+          type: string
+        kind:
+          type: string
+        occurredAt:
+          anyOf:
+            - type: string
+            - type: "null"
+      required:
+        - encounterId
+        - kind
+        - occurredAt
+      additionalProperties: false
+      description: "A link to one of the caller's visits — \"this letter belongs to that appointment\". `kind` is the
+        visit-kind ENUM CONSTANT rather than a rendered name: unlike a condition label, which is the person's own words,
+        a visit kind is one of eight closed values whose human name the reader's own bundle owns, so publishing the
+        constant is what lets a German reader and an English one each see it named correctly."
     InboundDocumentEnvelope:
       type: object
       properties:
@@ -36804,6 +36854,10 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/DocumentConditionLink"
+        encounterLinks:
+          type: array
+          items:
+            $ref: "#/components/schemas/DocumentEncounterLink"
         servingClass:
           type: string
           enum:
@@ -36861,6 +36915,7 @@ components:
         - factCount
         - pendingCount
         - conditionLinks
+        - encounterLinks
         - servingClass
         - hasContentIndex
         - contentIndexSource