@bongos/core 1.19.1060 → 1.19.1062

package/modules/copy-desk/tests/fixtures/word-docx.mjs

@@ -0,0 +1,131 @@
+// modules/copy-desk/tests/fixtures/word-docx.mjs — edit a downloaded page .docx
+// the way Word stores an edit (task 1004320 / BV2.TW09, ADR 0341 D12).
+//
+// The Word round-trip tests must not prove the reader against its own writer
+// only. So this fixture re-packs a file the way Word does, with its OWN zip
+// writer (data descriptors after each entry, zero sizes in the local headers,
+// entries in another order), and rewrites a line's paragraph the way Word
+// leaves one after typing: the text split across several runs with their own
+// properties and revision ids, proofing marks between them, smart quotes, and
+// tracked insertions and deletions.
+//
+// Shared by modules/copy-desk/tests/copy_docx.mjs and
+// tests/copy_desk_page_docx.mjs (a fixture, not a test: the runner discovers
+// tests/*.mjs only, not this folder).
+
+import zlib from 'node:zlib';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const docx = require('../../docx.js');
+
+// Every entry of a zip, by the module's own reader (reading is not what these
+// tests doubt; the re-pack below is independent of the module's writer).
+export function unzipAll(buf) {
+  const z = docx.readZip(buf);
+  if (!z.ok) throw new Error(`unzip: ${z.code} ${JSON.stringify(z.detail)}`);
+  return new Map([...z.parts].map(([k, v]) => [k, v.toString('utf8')]));
+}
+
+// Pack entries the way Word writes a .docx: general-purpose flag bit 3 (sizes
+// and CRC in a data descriptor after the data, zeros in the local header),
+// deflated, in the order given.
+export function wordZip(entries) {
+  const out = [];
+  const central = [];
+  let offset = 0;
+  for (const [name, text] of entries) {
+    const data = Buffer.from(text, 'utf8');
+    const packed = zlib.deflateRawSync(data, { level: 6 });
+    const crc = docx.crc32(data);
+    const nameBuf = Buffer.from(name, 'utf8');
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(0x0008 | 0x0800, 6);
+    local.writeUInt16LE(8, 8);
+    local.writeUInt16LE(0x6000, 10);
+    local.writeUInt16LE(0x5b3c, 12);
+    local.writeUInt16LE(nameBuf.length, 26);
+    const desc = Buffer.alloc(16);
+    desc.writeUInt32LE(0x08074b50, 0);
+    desc.writeUInt32LE(crc, 4);
+    desc.writeUInt32LE(packed.length, 8);
+    desc.writeUInt32LE(data.length, 12);
+    const c = Buffer.alloc(46);
+    c.writeUInt32LE(0x02014b50, 0);
+    c.writeUInt16LE(45, 4);
+    c.writeUInt16LE(20, 6);
+    c.writeUInt16LE(0x0008 | 0x0800, 8);
+    c.writeUInt16LE(8, 10);
+    c.writeUInt16LE(0x6000, 12);
+    c.writeUInt16LE(0x5b3c, 14);
+    c.writeUInt32LE(crc, 16);
+    c.writeUInt32LE(packed.length, 20);
+    c.writeUInt32LE(data.length, 24);
+    c.writeUInt16LE(nameBuf.length, 28);
+    c.writeUInt32LE(offset, 42);
+    out.push(local, nameBuf, packed, desc);
+    central.push(c, nameBuf);
+    offset += 30 + nameBuf.length + packed.length + 16;
+  }
+  const cd = Buffer.concat(central);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(entries.length, 8);
+  end.writeUInt16LE(entries.length, 10);
+  end.writeUInt32LE(cd.length, 12);
+  end.writeUInt32LE(offset, 16);
+  return Buffer.concat([...out, cd, end]);
+}
+
+// Re-pack a downloaded file after changing its document part (and optionally
+// other parts), in reverse entry order, the way a save by another program
+// reorders them.
+export function resave(buf, { document, drop = [], parts = {} } = {}) {
+  const all = unzipAll(buf);
+  if (document) all.set('word/document.xml', document(all.get('word/document.xml')));
+  for (const [k, v] of Object.entries(parts)) all.set(k, v);
+  for (const k of drop) all.delete(k);
+  return wordZip([...all].reverse());
+}
+
+// The paragraph that holds a line's content control, as it stands.
+const LINE_PARA = (key) => new RegExp(`<w:p>(?:(?!<w:p>).)*?<w:tag w:val="${key}"/>.*?</w:p>`, 's');
+const LINE_PARA_STYLED = (key) => new RegExp(`<w:p><w:pPr>(?:(?!<w:p>).)*?<w:tag w:val="${key}"/>.*?</w:p>`, 's');
+export function lineParagraph(xml, key) {
+  const m = LINE_PARA_STYLED(key).exec(xml) || LINE_PARA(key).exec(xml);
+  if (!m) throw new Error(`no paragraph for ${key}`);
+  return m[0];
+}
+
+// Replace the runs inside a line's content control with Word-shaped runs.
+export function typeInto(xml, key, runsXml) {
+  const para = lineParagraph(xml, key);
+  const edited = para.replace(/<w:sdtContent>[\s\S]*?<\/w:sdtContent>/, () => `<w:sdtContent>${runsXml}</w:sdtContent>`);
+  return xml.replace(para, () => edited);
+}
+
+// Word's runs for a typed sentence: each part its own run, some with
+// properties and revision ids, proofing marks between them.
+export function wordRuns(parts) {
+  return parts.map((p, i) => {
+    const rPr = i % 2 ? '<w:rPr><w:rFonts w:ascii="Calibri"/><w:lang w:val="en-GB"/></w:rPr>' : '';
+    const proof = i === 1 ? '<w:proofErr w:type="spellStart"/>' : i === 2 ? '<w:proofErr w:type="spellEnd"/>' : '';
+    return `${proof}<w:r w:rsidR="00A1B2C${i}" w:rsidRPr="00D4E5F${i}">${rPr}<w:t xml:space="preserve">${p}</w:t></w:r>`;
+  }).join('');
+}
+
+// A tracked change: the insertion is text now, the deletion is not.
+export function trackedInsert(text) {
+  return `<w:ins w:id="91" w:author="Artist" w:date="2026-09-28T10:00:00Z"><w:r><w:t xml:space="preserve">${text}</w:t></w:r></w:ins>`;
+}
+export function trackedDelete(text) {
+  return `<w:del w:id="92" w:author="Artist" w:date="2026-09-28T10:00:00Z"><w:r><w:delText xml:space="preserve">${text}</w:delText></w:r></w:del>`;
+}
+
+// Remove every content control, keeping its runs: what an editor that does
+// not keep controls leaves behind (the upload then maps by position).
+export function stripControls(xml) {
+  return xml.replace(/<w:sdt><w:sdtPr>[\s\S]*?<\/w:sdtPr><w:sdtContent>([\s\S]*?)<\/w:sdtContent><\/w:sdt>/g, (m, inner) => inner);
+}

package/modules/lifecycle/lifecycle.js

@@ -26,6 +26,7 @@ const activity = require('./activity');
 const mingle = require('./mingle');
 const pageTweakReads = require('./page-tweak-reads');
 const pageTweakClaim = require('./page-tweak-claim');
+const pageTweakWrite = require('./page-tweak-write');
 
 module.exports = {
   // --- retired doorway leaks (ADR 0093 §3) ---------------------------------
@@ -118,6 +119,13 @@ module.exports = {
   // it is page-shaped because the find-or-create has to share the claim's
   // transaction. See modules/lifecycle/page-tweak-claim.js.
   webClaimPageTweak: (...a) => pageTweakClaim.webClaimPageTweak(...a),
+  // The page draft's autosave and the submit (task 1004319 / BV2.TW08, ADR 0341
+  // D4, D11): a holder-guarded description write that skips an unchanged save,
+  // and the submit's one transaction (engineer tasks for unplaced lines, the
+  // frozen batch, the web claim released, the round back to ready). D11 names
+  // updateTaskDescription and releaseClaim; see modules/lifecycle/page-tweak-write.js.
+  updateHeldTaskDescription: (...a) => pageTweakWrite.updateHeldTaskDescription(...a),
+  submitPageTweak: (...a) => pageTweakWrite.submitPageTweak(...a),
   listVersions: (...a) => db.listVersions(...a),
   versionProgress: (...a) => db.versionProgress(...a),
   recentShippedTasks: (...a) => db.recentShippedTasks(...a),

package/modules/lifecycle/page-tweak-reads.js

@@ -37,10 +37,17 @@ const api = require('../../src/module-api');
 //     per task), joined once, rather than a correlated subquery per task:
 //     claims has no full index on task_id, so a per-row LATERAL would scan it
 //     once per round.
-async function listPageTweakTasks() {
+//
+// `pageId` narrows it to ONE page's rounds (task 1004319 / TW08): the draft
+// autosave runs this on every debounced save, and a page's rounds are a handful
+// while the instance's grow without bound. The prefix is matched with left(),
+// not LIKE, the page claim's own rule (an `_` in an id is never a wildcard).
+async function listPageTweakTasks({ pageId = null } = {}) {
+  const prefix = pageId ? `page-tweak/${pageId}/` : null;
   const { rows } = await api.pool.query(
     `WITH pt AS (
        SELECT t.id FROM tasks t WHERE t.source = 'page-tweak'
+          AND ($1::text IS NULL OR left(t.source_ref, length($1::text)) = $1::text)
      ), web AS (
        SELECT DISTINCT ON (c.task_id) c.task_id, c.builder_id
          FROM claims c JOIN pt ON pt.id = c.task_id
@@ -60,7 +67,9 @@ async function listPageTweakTasks() {
        LEFT JOIN web wc ON wc.task_id = t.id
        LEFT JOIN builders ab ON ab.id = wc.builder_id
       WHERE t.source = 'page-tweak'
-      ORDER BY t.id ASC`
+        AND ($1::text IS NULL OR left(t.source_ref, length($1::text)) = $1::text)
+      ORDER BY t.id ASC`,
+    [prefix]
   );
   return rows;
 }

package/modules/lifecycle/page-tweak-write.js

@@ -0,0 +1,192 @@
+// modules/lifecycle/page-tweak-write.js — the page draft save and the submit
+// (task 1004319 / BV2.TW08, ADR 0341 D4, D7, D11).
+//
+// On the `lifecycle` port because tasks and claims are this module's tables and
+// copy-desk may only cross the wall through a port (ADR 0083, ADR 0093 §2). What
+// the draft and the batch SAY (the fenced blocks, the resolution against the page
+// reading, the engineer task an unplaced line files) is copy-desk's and is handed
+// in as a function; the transaction and the holder check are lifecycle's.
+//
+// BOTH ARE HOLDER-ONLY. The caller must hold the task's open WEB claim
+// (worktree_name NULL and creator_session_id NULL, the claim the page claim
+// takes). The check runs inside the transaction, after the task row is locked
+// FOR UPDATE, the same lock claimTask and the page claim take, so a save cannot
+// interleave with a claim or a release of the same round.
+//
+// AN AUTOSAVE THAT CHANGES NOTHING WRITES NOTHING. The editor autosaves often
+// (it debounces; the server accepts a whole-draft replace). When the composed
+// description equals the stored one, the transaction ends without an UPDATE, so
+// `updated_at` and every reader that sorts by it stay where they were.
+//
+// ADR 0341 D11 names the port entries updateTaskDescription, webClaimTask and
+// releaseClaim. They landed page-shaped, as TW06's webClaimPageTweak did: the
+// description update is holder-guarded (updateHeldTaskDescription, so no caller
+// can rewrite a task it does not hold through the port), and the release runs
+// INSIDE the submit's transaction (submitPageTweak), because the batch, the
+// engineer tasks and the release must commit together or not at all.
+//
+// Outcomes are returned, not thrown, so the route maps each to a named answer:
+//   saved | unchanged | submitted
+//   not_found      no such task
+//   wrong_source   the task is not of the source the caller named
+//   not_held       the caller does not hold its open web claim (holder named)
+//   refused        copy-desk's function refused (its refusal is passed back)
+
+'use strict';
+
+const api = require('../../src/module-api');
+const db = require('./db');
+
+function activePoolFor(deps) {
+  return (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : api.pool;
+}
+
+// Lock the task, then read its open claim. Returns { task, claim } or an outcome.
+async function lockHeld(client, { taskId, builderId, source }) {
+  const { rows } = await client.query(
+    `SELECT id, status, title, description, source, source_ref, version_id, goal_id, touches
+       FROM tasks WHERE id = $1 FOR UPDATE`,
+    [taskId]
+  );
+  const task = rows[0];
+  if (!task) return { outcome: 'not_found' };
+  if (source && task.source !== source) return { outcome: 'wrong_source', task };
+  const { rows: held } = await client.query(
+    `SELECT c.id, c.builder_id, c.worktree_name, c.creator_session_id, b.github_login, b.display_name
+       FROM claims c JOIN builders b ON b.id = c.builder_id
+      WHERE c.task_id = $1 AND c.released_at IS NULL
+      LIMIT 1`,
+    [taskId]
+  );
+  const claim = held[0] || null;
+  const web = !!claim && claim.worktree_name == null && claim.creator_session_id == null;
+  if (!claim || !web || String(claim.builder_id) !== String(builderId)) {
+    return {
+      outcome: 'not_held',
+      task,
+      holder: claim ? { id: String(claim.builder_id), login: claim.github_login || null, name: claim.display_name || null, writing: web } : null,
+    };
+  }
+  return { task, claim };
+}
+
+// updateHeldTaskDescription({ taskId, builderId, source, compose }, deps)
+//
+//   compose(task) -> { ok: true, description } | { ok: false, code, detail }
+//
+// The page draft's autosave (PUT /copy-desk/pages/:pageId/draft). Writes the
+// composed description when it differs from the stored one.
+async function updateHeldTaskDescription({ taskId, builderId, source = null, compose }, deps = {}) {
+  const client = await activePoolFor(deps).connect();
+  try {
+    await client.query('BEGIN');
+    const held = await lockHeld(client, { taskId, builderId, source });
+    if (held.outcome) { await client.query('ROLLBACK'); return held; }
+    const r = compose(held.task);
+    if (!r || !r.ok) { await client.query('ROLLBACK'); return { outcome: 'refused', refusal: r, task: held.task }; }
+    if (r.description === held.task.description) {
+      await client.query('ROLLBACK');
+      return { outcome: 'unchanged', task: held.task };
+    }
+    const { rows } = await client.query(
+      `UPDATE tasks SET description = $2, updated_at = now() WHERE id = $1
+       RETURNING id, status, description, source_ref, updated_at`,
+      [taskId, r.description]
+    );
+    await client.query('COMMIT');
+    return { outcome: 'saved', task: rows[0] };
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+// submitPageTweak({ taskId, builderId, versionId, freeze }, deps)
+//
+//   freeze(task) -> { ok: true, unplaced: [{ sourceRef, title, description, touches }],
+//                     description(unplacedTaskIds) -> string }
+//                 | { ok: false, code, detail }
+//
+// The submit (POST /copy-desk/pages/:pageId/submit), one transaction:
+//   1. each unplaced rewrite files its engineer task (source page-tweak-unplaced,
+//      backlog, engineer), or finds the one its source ref already filed;
+//   2. the description gains the frozen `page-tweak` block naming those tasks;
+//   3. the artist's web claim is RELEASED (outcome 'partial': their part is done
+//      and the task goes on) and the task returns to `ready`, so the round reads
+//      `submitted` and sits in the /tweak queue (ADR 0341 D7).
+// The released claim is the one the payee rule reads (ADR 0341 D10).
+async function submitPageTweak({ taskId, builderId, versionId = null, freeze }, deps = {}) {
+  const createTask = deps.createTask || db.createTask;
+  const client = await activePoolFor(deps).connect();
+  try {
+    await client.query('BEGIN');
+    const held = await lockHeld(client, { taskId, builderId, source: 'page-tweak' });
+    if (held.outcome) { await client.query('ROLLBACK'); return held; }
+    const plan = freeze(held.task);
+    if (!plan || !plan.ok) { await client.query('ROLLBACK'); return { outcome: 'refused', refusal: plan, task: held.task }; }
+
+    // The engineer tasks an earlier submit of this round already filed, in ONE
+    // read (a resubmit after a send-back finds them). Only the missing ones go
+    // through createTask, the single create chokepoint, one at a time.
+    const wanted = plan.unplaced || [];
+    const existing = new Map();
+    if (wanted.length) {
+      const { rows: found } = await client.query(
+        'SELECT id, source_ref FROM tasks WHERE source = $1 AND source_ref = ANY($2::text[])',
+        [wanted[0].source, wanted.map((u) => u.sourceRef)]
+      );
+      for (const f of found) if (!existing.has(f.source_ref)) existing.set(f.source_ref, String(f.id));
+    }
+    const filed = [];
+    for (const u of wanted) {
+      if (existing.has(u.sourceRef)) { filed.push({ id: existing.get(u.sourceRef), key: u.key, created: false }); continue; }
+      const t = await createTask({
+        versionId: versionId != null ? versionId : held.task.version_id,
+        // The building version's catch-all goal, declared out loud (BV1.R11),
+        // exactly as the round itself and a copy proposal land.
+        allowCatchAll: true,
+        title: u.title,
+        description: u.description,
+        // BACKLOG (ADR 0341 D4): an engineer's triage decides when, and the
+        // page does not wait for it.
+        status: 'backlog',
+        kind: 'feature',
+        discipline: 'engineer',
+        priority: 4,
+        touches: u.touches || [],
+        source: u.source,
+        sourceRef: u.sourceRef,
+        createdBy: builderId,
+      }, { client });
+      filed.push({ id: String(t.id), key: u.key, created: true });
+    }
+
+    const description = plan.description(filed.map((f) => f.id));
+    const { rows } = await client.query(
+      `UPDATE tasks SET description = $2, status = 'ready', updated_at = now() WHERE id = $1
+       RETURNING id, status, description, source_ref, updated_at`,
+      [taskId, description]
+    );
+    await releaseClaim(client, held.claim.id);
+    await client.query('COMMIT');
+    return { outcome: 'submitted', task: rows[0], unplaced_tasks: filed, released_claim_id: String(held.claim.id) };
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+// Release one claim inside the caller's transaction. The task's status is the
+// caller's to set (the submit sets `ready` with the same UPDATE as the batch).
+async function releaseClaim(client, claimId, outcome = 'partial') {
+  await client.query(
+    'UPDATE claims SET released_at = now(), outcome = $2 WHERE id = $1 AND released_at IS NULL',
+    [claimId, outcome]
+  );
+}
+
+module.exports = { updateHeldTaskDescription, submitPageTweak };

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1060",
+  "version": "1.19.1062",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.1060",
+      "version": "1.19.1062",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1060",
+  "version": "1.19.1062",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -7661,5 +7661,17 @@
       "id": "1004318",
       "text": "An artist can now ask \"what should I tweak next?\" and get one page back, with the reason in plain words, such as \"2 people asked for it\". Pages people asked for come first, then pages whose words changed since their last tweak"
     }
+  ],
+  "1.19.1061": [
+    {
+      "id": "1004319",
+      "text": "An artist's page rewrite is now saved as they type and can be submitted. The draft rests on the page's own tweak task, and saving the same words again changes nothing. Submitting freezes the rewrite for a /tweak session to app"
+    }
+  ],
+  "1.19.1062": [
+    {
+      "id": "1004320",
+      "text": "An artist can now download any page's words as a Word document, work on it offline, and upload it back. The upload goes into their draft, never straight to the site, and only the lines they actually changed in Word are taken,"
+    }
   ]
 }

package/scripts/gds/fitness-checks-write-validation.js

@@ -42,6 +42,10 @@ const WRITE_VALIDATION_EXEMPT = new Set([
   'PATCH /me/render',             // { widgets: <bool>|null }      — renderPrefs.validatePatch
   'PATCH /me/display-name',       // { display_name }              — displayName.validate
   'PATCH /me/profile-nudge',      // { dismissed: <bool>|null }    — profileNudgePrefs.validatePatch
+  // Not a JSON body at all: the raw .docx bytes (task 1004320, ADR 0341 D12), capped by
+  // the route's own express.raw parser and read by docx.readUpload, which refuses
+  // anything that is not a bounded, readable Word file (not_a_docx / upload_too_large).
+  'POST /copy-desk/pages/:pageId/draft.docx',
 ]);
 
 // KNOWN GAPS, NOT EXEMPTIONS (task 1002551 / BV1.R109b → tracked by task 1002552).

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.1060'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1062'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');