@bongos/core 1.19.1060 → 1.19.1062

package/docs/api/openapi.json

@@ -5311,6 +5311,234 @@
         ]
       }
     },
+    "/copy-desk/pages/{pageId}/draft": {
+      "put": {
+        "operationId": "put_copy_desk_pages_pageId_draft",
+        "tags": [
+          "copy-desk"
+        ],
+        "summary": "PUT /copy-desk/pages/:pageId/draft",
+        "description": "------------------------------------------------------------------------- PUT /copy-desk/pages/:pageId/draft — autosave the artist's draft (task 1004319 / BV2.TW08, ADR 0341 D4). Body: { reading_hash, lines: [{ key, after }] }, the WHOLE draft: every line the artist has changed. The saved draft becomes exactly that (a line sent back at its current text is dropped, so only changed lines are stored). rank: any signed-in builder; only the HOLDER of the page's writing claim (the web claim the page claim took) may save, checked in the lifecycle transaction. Every target is resolved from the page reading by key: section, current text (`before`) and placement are the reading's, never the body's. A body built on an older reading is refused `reading_moved`, whole, since its keys may now mean other lines. Cheap and idempotent: a save that resolves to the draft already stored writes nothing (200 `unchanged`; `updated_at` does not move). The editor debounces; the server only has to make a repeated save free. 200 saved | unchanged with the draft and \"N of M rewritten\" 409 page_not_held the caller does not hold the page (holder named) 409 no_open_round the page has no round: claim it first 409 reading_moved · 400 unknown_line / line_empty / line_too_long -------------------------------------------------------------------------\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/copy-desk/routes/copy-desk.js",
+        "parameters": [
+          {
+            "name": "pageId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `pageId`."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PutCopyDeskPagesPageIdDraftRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PutCopyDeskPagesPageIdDraftResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/copy-desk/pages/{pageId}/draft.docx": {
+      "get": {
+        "operationId": "get_copy_desk_pages_pageId_draft_docx",
+        "tags": [
+          "copy-desk"
+        ],
+        "summary": "GET /copy-desk/pages/:pageId/draft.docx",
+        "description": "------------------------------------------------------------------------- GET /copy-desk/pages/:pageId/draft.docx — download the page's words as a Word document, to work on offline (task 1004320 / BV2.TW09, ADR 0341 D12). The file is built from the page reading plus the open round's draft (a line the artist has rewritten shows its rewrite). A draft saved on an older reading is not shown, since its keys may now name other lines. rank: any signed-in builder. The words are the page's own, and the draft is on a task description every builder can already read; only the upload is the holder's. -------------------------------------------------------------------------\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/copy-desk/routes/copy-desk.js",
+        "parameters": [
+          {
+            "name": "pageId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `pageId`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      },
+      "post": {
+        "operationId": "post_copy_desk_pages_pageId_draft_docx",
+        "tags": [
+          "copy-desk"
+        ],
+        "summary": "POST /copy-desk/pages/:pageId/draft.docx",
+        "description": "------------------------------------------------------------------------- POST /copy-desk/pages/:pageId/draft.docx — upload the Word file back into the DRAFT (task 1004320 / BV2.TW09, ADR 0341 D12). Never to the site: the words land in the round's draft block, exactly where the autosave puts them, through the same port call (holder only) and the same resolver (every target from the page reading by key, never from the file). Body: the .docx bytes (Content-Type: the Word type, application/zip or application/octet-stream), at most docx.MAX_UPLOAD_BYTES. rank: any signed-in builder; only the HOLDER of the page's writing claim. A MERGE, not a replace: a line is taken from the file only when the artist changed it in Word (against the text the download showed), so a line they rewrote in the studio after downloading keeps that rewrite. 200 saved | unchanged the draft, the counter, and `merge` (which lines came from the file, and how they were matched) 409 structure_changed a line added, dropped or reordered, or a heading changed; each is named (section, first words) 409 wrong_page · reading_moved · page_not_held · no_open_round 413 upload_too_large · 415 not_a_docx -------------------------------------------------------------------------\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/copy-desk/routes/copy-desk.js",
+        "parameters": [
+          {
+            "name": "pageId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `pageId`."
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "additionalProperties": true
+              }
+            }
+          },
+          "x-validated": false,
+          "x-body-undocumented": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostCopyDeskPagesPageIdDraftDocxResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/copy-desk/pages/{pageId}/submit": {
+      "post": {
+        "operationId": "post_copy_desk_pages_pageId_submit",
+        "tags": [
+          "copy-desk"
+        ],
+        "summary": "POST /copy-desk/pages/:pageId/submit",
+        "description": "------------------------------------------------------------------------- POST /copy-desk/pages/:pageId/submit — freeze the draft and queue the page for /tweak (task 1004319 / BV2.TW08, ADR 0341 D4, D7). Body: {} (it freezes the draft already on the task; nothing is taken from the request). rank: any signed-in builder; the holder only. One lifecycle transaction: * every draft line is re-resolved on the CURRENT page reading; a line the page no longer shows is refused by name (target_gone), as are an ambiguous one and a {…} hole added or dropped. Any refusal refuses the submit, listing the lines, and nothing is frozen; * a rewrite of an UNPLACED line (and of shared shell text with no registry row) leaves the batch and files its own engineer task (source page-tweak-unplaced, backlog), carrying the page, the line and the wording. The page does not wait for it; * the rest is frozen into the `page-tweak` block with each line's file, line and string id from the reading, naming the engineer tasks; * the artist's web claim is released and the task goes back to `ready`: the round reads `submitted`, the /tweak queue. 200 submitted with the batch, the engineer tasks, and where \"next up\" reads (GET /copy-desk/next) 200 already_submitted a repeated submit by the round's artist 409 lines_refused · nothing_to_submit · page_not_held · no_open_round -------------------------------------------------------------------------\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/copy-desk/routes/copy-desk.js",
+        "parameters": [
+          {
+            "name": "pageId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `pageId`."
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "additionalProperties": true
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/copy-desk/proposals": {
       "post": {
         "operationId": "post_copy_desk_proposals",
@@ -24883,6 +25111,29 @@
         ],
         "additionalProperties": false
       },
+      "PostCopyDeskPagesPageIdDraftDocxResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "outcome": {},
+          "page_id": {},
+          "round": {},
+          "draft": {},
+          "counter": {},
+          "merge": {}
+        },
+        "required": [
+          "ok",
+          "outcome",
+          "page_id",
+          "round",
+          "draft",
+          "counter",
+          "merge"
+        ]
+      },
       "PostCopyDeskProposalsRequest": {
         "type": "object",
         "properties": {
@@ -28182,6 +28433,45 @@
           "criteria"
         ]
       },
+      "PutCopyDeskPagesPageIdDraftRequest": {
+        "type": "object",
+        "properties": {
+          "reading_hash": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64
+          },
+          "lines": {
+            "type": "array"
+          }
+        },
+        "required": [
+          "reading_hash",
+          "lines"
+        ],
+        "additionalProperties": false
+      },
+      "PutCopyDeskPagesPageIdDraftResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "outcome": {},
+          "page_id": {},
+          "round": {},
+          "draft": {},
+          "counter": {}
+        },
+        "required": [
+          "ok",
+          "outcome",
+          "page_id",
+          "round",
+          "draft",
+          "counter"
+        ]
+      },
       "PutGovernmentRanksRankKeyPermissionsPermissionKeyResponse": {
         "type": "object",
         "properties": {
@@ -28385,9 +28675,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 449,
-  "x-schema-count": 484,
-  "x-undocumented-bodies": 9,
-  "x-response-schemas": 331,
+  "x-endpoint-count": 453,
+  "x-schema-count": 487,
+  "x-undocumented-bodies": 10,
+  "x-response-schemas": 333,
   "x-generated-by": "scripts/gds/gen-api-docs.js"
 }

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 449 endpoints across 76 route files.
+> **Generated from the live route files** — the route file is authoritative. 453 endpoints across 76 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
 Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust-boundary-server-enforced-permissions.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -210,7 +210,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/connections/requests` | `any-builder` | — | MY pending requests, both directions (own data). |
 | GET | `/api/bongos/connections/suggestions` | `any-builder` | — | "builders you may know" (R21, task 1002297; ADR 0202 D5). |
 
-## `copy-desk` (11)
+## `copy-desk` (15)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -221,6 +221,10 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/copy-desk/pages/:pageId` | `any-builder` | — | ------------------------------------------------------------------------- GET /copy-desk/pages/:pageId — one page: status, changelog, the… |
 | POST | `/api/bongos/copy-desk/pages/:pageId/asks` | `any-builder` | `reason` | ------------------------------------------------------------------------- POST /copy-desk/pages/:pageId/asks — ask for a page (task 10043… |
 | POST | `/api/bongos/copy-desk/pages/:pageId/claim` | `any-builder` | validated | ------------------------------------------------------------------------- POST /copy-desk/pages/:pageId/claim — claim a page's tweak (tas… |
+| PUT | `/api/bongos/copy-desk/pages/:pageId/draft` | `any-builder` | `reading_hash`, `lines` | ------------------------------------------------------------------------- PUT /copy-desk/pages/:pageId/draft — autosave the artist's draf… |
+| GET | `/api/bongos/copy-desk/pages/:pageId/draft.docx` | `any-builder` | — | ------------------------------------------------------------------------- GET /copy-desk/pages/:pageId/draft.docx — download the page's w… |
+| POST | `/api/bongos/copy-desk/pages/:pageId/draft.docx` | `any-builder` | _undocumented_ | ------------------------------------------------------------------------- POST /copy-desk/pages/:pageId/draft.docx — upload the Word file… |
+| POST | `/api/bongos/copy-desk/pages/:pageId/submit` | `any-builder` | validated | ------------------------------------------------------------------------- POST /copy-desk/pages/:pageId/submit — freeze the draft and que… |
 | POST | `/api/bongos/copy-desk/proposals` | `any-builder` | `string_id`, `proposed_text`, `why`, `file`, `line`, `flag_id` | ------------------------------------------------------------------------- POST /copy-desk/proposals — an artist proposes new wording, and… |
 | GET | `/api/bongos/copy-desk/queue` | `any-builder` | — | ------------------------------------------------------------------------- GET /copy-desk/queue — the artist's working list. |
 | GET | `/api/bongos/copy-desk/strings` | `any-builder` | — | ------------------------------------------------------------------------- GET /copy-desk/strings — search the inventory, to find somethin… |
@@ -798,5 +802,5 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 
 ---
 
-> 9 write endpoint(s) take a JSON body with no declared validator schema — their fields are not yet machine-documented. Adding a `validateOrRespond` schema (`src/bongos/routes/_helpers.js`) surfaces them here automatically.
+> 10 write endpoint(s) take a JSON body with no declared validator schema — their fields are not yet machine-documented. Adding a `validateOrRespond` schema (`src/bongos/routes/_helpers.js`) surfaces them here automatically.
 

package/docs/module-api-changelog.md

@@ -2607,5 +2607,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.1058 with no explicit bump. run 36415558760. (task 1002620)
   1.19.1060 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.1059 with no explicit bump. run 36418832327. (task 1002620)
+  1.19.1061 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.1060 with no explicit bump. run 36423029975. (task 1002620)
+  1.19.1062 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.1061 with no explicit bump. run 36428277106. (task 1002620)
 ---------------------------------------------------------------------------
 ```