@bongos/core 1.19.1062 → 1.19.1064

package/modules/lifecycle/migrations/lifecycle_013_task_visual_slots.sql

@@ -0,0 +1,52 @@
+-- lifecycle_013_task_visual_slots.sql — a task can carry NAMED visuals, not only
+-- the one (task 1004322 / BV2.TW11, goal 1000095; ADR 0341 D7 and its builder
+-- pick 9).
+--
+-- WHY. core_223 gave a task ONE optional image (tasks.visual_url + visual_alt),
+-- the picture beside its value summary. A page tweak needs eight: the applied
+-- page before and after, on desktop and on a phone, in light and in dark. The
+-- Approval queue (TW12) shows the artist exactly those renders, images of the
+-- applied branch, never a page built from the batch, which is what keeps ADR
+-- 0233's "nothing renders a task description as product copy" true. One column
+-- cannot hold eight pictures, and eight columns would be a schema for one
+-- feature, so a visual gets a NAME and a row.
+--
+-- THE SINGLE VISUAL IS UNTOUCHED. tasks.visual_url stays the ship-time picture
+-- every existing reader renders (the hall, the status feed); a slot is a
+-- separate, named picture a reader asks for by name. Nothing here moves,
+-- copies or backfills the existing column.
+--
+-- A MODULE TABLE, because ADR 0083 lets a module migration create only its own
+-- lifecycle_-namespaced tables; it references the core tasks table the way
+-- lifecycle_010 does, and never alters it.
+--
+-- THE SAME AUDIENCE AS THE ONE VISUAL. A slot's file is stored and served by the
+-- existing task-visuals store (task-<id>-<hex>.<ext>, GET /task-visuals/:name),
+-- whose serve route derives who may see an image from the TASK it names. So a
+-- slot adds no privacy axis, exactly as core_223 promised of the column.
+--
+-- PORTABLE and replay-safe: IF NOT EXISTS throughout, no instance data.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS lifecycle_task_visual_slots (
+  task_id    bigint NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+
+  -- The slot's name: lowercase words joined by dashes, such as
+  -- 'after-phone-dark'. The vocabulary a page tweak uses is declared once in
+  -- modules/lifecycle/task-visuals.js (TWEAK_RENDER_SLOTS); the column checks only
+  -- the SHAPE, so a later feature can name its own slots without a migration.
+  slot       text   NOT NULL CHECK (slot ~ '^[a-z0-9]+(-[a-z0-9]+){0,5}$' AND length(slot) <= 48),
+
+  -- The served URL (/api/bongos/task-visuals/<file>), minted by the store.
+  visual_url text   NOT NULL,
+  visual_alt text,
+
+  updated_at timestamptz NOT NULL DEFAULT now(),
+
+  -- One picture per (task, slot): attaching a slot again REPLACES it, and the
+  -- route unlinks the superseded file.
+  PRIMARY KEY (task_id, slot)
+);
+
+COMMIT;

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

@@ -0,0 +1,74 @@
+// modules/lifecycle/page-tweak-hold.js — the ONE definition of "a page tweak
+// waiting for its artist" (task 1004322 / BV2.TW11, ADR 0341 D7).
+//
+// THE HOLD. A page tweak transcribes words an artist wrote, so its artist must
+// see the applied page before it ships (spec decision 4). When a page tweak's
+// grade PASSES, applyGrade records the grade but does not promote `completed`
+// to `confirmed`: the task waits at `completed` until the artist approves it
+// (TW12's approve route does the promotion the grade withheld) or sends it back.
+//
+// WHY ONE FILE. Five readers must agree on this one fact, and a second copy of
+// it is how they would drift: applyGrade (do not promote), the publish-branch
+// route (publish, but never arm auto-merge), the publish-status route (never
+// nudge the merge), ship.js (publish the branch and say the page is waiting)
+// and strand-watch / grade-recover (a held pass is not a failed grade). Every
+// one of them asks the questions below.
+//
+// PURE: no require, no fs, no DB. The scripts under scripts/gds/ require it
+// directly, so it must load without the module doorway.
+//
+// Every other task is untouched by construction: each predicate is false unless
+// the task's source is exactly 'page-tweak'.
+
+'use strict';
+
+// The task source the page claim writes (modules/copy-desk/pages.js SOURCE).
+// Restated, not required: copy-desk is another module, and this file requires
+// nothing so that the CLI can load it.
+const PAGE_TWEAK_SOURCE = 'page-tweak';
+
+// The derived round state this hold produces (ADR 0341 D7's table).
+const HOLD_STATE = 'waiting_for_artist';
+
+function isPageTweak(task) {
+  return !!task && task.source === PAGE_TWEAK_SOURCE;
+}
+
+// Is this task held for its artist? `gradePassed` is the task's grade row's
+// `passed` (task_grades keeps one row per task, the latest). Only a strict
+// `true` holds: a missing grade, or a failed one, is the ordinary `completed`
+// that /grade-recover handles.
+function isHeldForArtist(task, gradePassed) {
+  return isPageTweak(task) && task.status === 'completed' && gradePassed === true;
+}
+
+// What ship.js prints when it parks a held pass. One place, so the ship, the
+// re-grade and the resume all say the same thing.
+function heldLines(taskId, { prUrl = null } = {}) {
+  return [
+    '',
+    `Task #${taskId} passed its grade and is WAITING FOR THE ARTIST (ADR 0341 D7).`,
+    '  This is a page tweak: the artist approves the applied page before it ships.',
+    prUrl
+      ? `  The branch and its PR are published (${prUrl}); auto-merge is NOT armed.`
+      : '  The branch is published; auto-merge is NOT armed.',
+    '  The task stays at completed. Approve promotes it to land; send-back returns it to the /tweak queue.',
+    '  Nothing more to do here.',
+  ];
+}
+
+// The auto-merge result the publish route reports for a held pass, in the shape
+// enableAutoMergeDetailed returns, so the route's response carries its reason
+// on the field it already has (auto_merge_reason).
+const HELD_NOT_ARMED = Object.freeze({
+  ok: false,
+  reason: 'held for the artist (ADR 0341 D7): a page tweak lands only after its artist approves it',
+});
+
+module.exports = {
+  HELD_NOT_ARMED,
+  HOLD_STATE,
+  isPageTweak,
+  isHeldForArtist,
+  heldLines,
+};

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

@@ -12,6 +12,7 @@
 'use strict';
 
 const api = require('../../src/module-api');
+const hold = require('./page-tweak-hold');
 
 // Every page-tweak task, oldest first, with what the round state (D7) and the
 // changelog (D8) need beside the task itself:
@@ -93,4 +94,35 @@ async function shippedTasksTouchingSince({ files, since, limit = 50 } = {}) {
   return rows;
 }
 
-module.exports = { listPageTweakTasks, shippedTasksTouchingSince };
+// Is this task a page tweak held for its artist (ADR 0341 D7; task 1004322)?
+// The publish routes ask it before they arm or nudge a merge: a held pass is
+// published so the Approval queue can show the applied branch, but it must not
+// land until the artist approves. One row: the task's source and status, and its
+// grade (task_grades keeps one row per task). The verdict is the shared pure
+// predicate, so this read and applyGrade cannot disagree about what "held" means.
+async function readTweakHold(taskId) {
+  const { rows } = await api.pool.query(
+    `SELECT t.source, t.status, g.passed AS grade_passed
+       FROM tasks t
+       LEFT JOIN task_grades g ON g.task_id = t.id
+      WHERE t.id = $1`,
+    [taskId]
+  );
+  const row = rows[0] || null;
+  return { held: !!row && hold.isHeldForArtist(row, row.grade_passed), page_tweak: hold.isPageTweak(row) };
+}
+
+// The publish routes' form of the question, FAIL-CLOSED: a read that throws
+// answers "held", so the route neither arms auto-merge nor nudges the merge.
+// That is the safe direction for every task: an ordinary confirmed task whose
+// PR was left un-armed still lands, because the publish reconciler's sweep
+// merges green PRs of confirmed tasks on its own (task 1162).
+async function heldForArtistFailClosed(taskId, read = readTweakHold) {
+  try {
+    return (await read(taskId)).held;
+  } catch (_) {
+    return true;
+  }
+}
+
+module.exports = { listPageTweakTasks, shippedTasksTouchingSince, heldForArtistFailClosed };

package/modules/lifecycle/routes/tasks.js

@@ -35,6 +35,7 @@ const { depRefusalRow } = require('../dead-deps.js');
 const { gradeQualityWhere } = require('../db-shared');
 const auth = api;
 const db = require('../db');
+const pageTweakReads = require('../page-tweak-reads'); const { HELD_NOT_ARMED } = require('../page-tweak-hold'); // ADR 0341 D7 (tests stub the read)
 const hierarchy = require('../hierarchy');
 const { suggestCriteria } = require('../criterion-suggest');
 // The orphan-task advisory (task 1002539) — pure, fail-open; see goal-advisory.js.
@@ -1184,7 +1185,8 @@ module.exports = function buildTasksRouter() {
       // task 1001431: ask WHY when arming fails. `auto_merge: false` on its own told the
       // builder nothing, and the commonest cause is a repo with allow_auto_merge OFF —
       // a permanent condition that reads exactly like a transient blip.
-      const autoMergeResult = await githubPush.enableAutoMergeDetailed({ nodeId: pr.node_id });
+      // task 1004322 (ADR 0341 D7): a page tweak held for its artist is PUBLISHED, never armed.
+      const autoMergeResult = (await pageTweakReads.heldForArtistFailClosed(id)) ? HELD_NOT_ARMED : await githubPush.enableAutoMergeDetailed({ nodeId: pr.node_id });
       const autoMerge = autoMergeResult.ok;
       // task 1139 (ADR 0058): attest the author's trust tier on the pushed sha so the
       // gate-review check can auto-approve a Metic+ author's gate-surface PR with no
@@ -1326,7 +1328,7 @@ module.exports = function buildTasksRouter() {
       // mirrors the reconcile-on-read precedent above (a GET that finishes the
       // land); best-effort so a merge-driver miss never turns the poll into a 502.
       let merge_driver = null;
-      if (!reconciled && !status.merged && status.pr_state === 'open') {
+      if (!reconciled && !status.merged && status.pr_state === 'open' && !(await pageTweakReads.heldForArtistFailClosed(id))) { // a held page tweak is never nudged (ADR 0341 D7)
         try {
           merge_driver = await githubPush.mergeIfGreen({ branch });
         } catch (e) {

package/modules/lifecycle/routes/visuals.js

@@ -14,6 +14,12 @@
 //   DELETE /tasks/:id/visual    take it back off       (claim holder | Archon)
 //   GET    /task-visuals/:name  serve one              (see the audience note)
 //
+// NAMED SLOTS (task 1004322 / BV2.TW11, lifecycle_013) — the same store, the same
+// gate, the same audience, one picture per name:
+//   POST   /tasks/:id/visuals/:slot   attach or replace a named one (claim holder | Archon)
+//   DELETE /tasks/:id/visuals/:slot   take it back off              (claim holder | Archon)
+//   GET    /tasks/:id/visuals         list them by name              (any builder)
+//
 // The twin of routes/bug-attachments.js, for the image a builder attaches to
 // their own shipped task instead of one the bot pulled out of #bugs. Storage +
 // screening live in ../task-visuals.js; all three routes live here rather than
@@ -191,6 +197,82 @@ module.exports = function buildTaskVisualsRouter() {
     }
   });
 
+  // ==========================================================================
+  // NAMED SLOTS (task 1004322 / BV2.TW11; ADR 0341 D7, builder pick 9)
+  // --------------------------------------------------------------------------
+  // A page tweak carries eight renders of the applied page (before and after,
+  // desktop and phone, light and dark), and the Approval queue shows them by
+  // name. Each slot is stored and screened exactly as the one visual is, and
+  // served by the same GET /task-visuals/:name, whose audience comes from the
+  // task. The slot name is validated before any byte is read.
+
+  // POST /tasks/:id/visuals/:slot — attach (or replace) one named visual.
+  router.post('/tasks/:id/visuals/:slot', auth.requireBuilder, visualUpload, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    const slot = req.params.slot;
+    if (!visuals.isSafeSlot(slot)) return res.fail('bad_slot', 400, { max_length: visuals.MAX_SLOT_LENGTH, example: visuals.TWEAK_RENDER_SLOTS[0] });
+    if (validateOrRespond(req, res, {
+      image_b64: { required: true, type: 'string', maxLength: VISUAL_B64_MAX, minLength: 1 },
+      content_type: { required: true, type: 'string', maxLength: 100, minLength: 1 },
+      alt: { type: 'string', maxLength: visuals.MAX_ALT_LENGTH },
+    })) return;
+    if (!(await gateTaskOwnership(req, res, id))) return;
+    const buf = Buffer.from(req.body.image_b64, 'base64');
+    const screened = visuals.screenImage(buf, req.body.content_type);
+    if (!screened.ok) {
+      return res.fail(`visual_${screened.reason}`, screened.reason === 'too_big' ? 413 : 400, {
+        max_bytes: visuals.MAX_BYTES,
+        accepted: Object.keys(visuals.EXT_BY_TYPE),
+      });
+    }
+    const task = await db.getTaskVisualAccess(id);
+    if (!task) return res.fail('task_not_found', 404);
+    try {
+      const stored = await visuals.persistImageBuffer(buf, { taskId: id, contentType: req.body.content_type });
+      if (!stored.ok) return res.fail(`visual_${stored.reason}`, 400);
+      const row = await db.setTaskVisualSlot({ taskId: id, slot, visualUrl: stored.url, visualAlt: visuals.normalizeAlt(req.body.alt) });
+      if (row && row.replaced_url && row.replaced_url !== stored.url) await visuals.deleteStored(row.replaced_url);
+      return res.status(201).json({ ok: true, slot, visual_url: row.visual_url, visual_alt: row.visual_alt, bytes: stored.bytes });
+    } catch (err) {
+      log.error({ taskId: id, slot, err: err && err.message }, 'task-visual slot upload failed');
+      return res.fail('visual_store_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // DELETE /tasks/:id/visuals/:slot — remove one named visual. Idempotent.
+  router.delete('/tasks/:id/visuals/:slot', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    const slot = req.params.slot;
+    if (!visuals.isSafeSlot(slot)) return res.fail('bad_slot', 400);
+    if (!(await gateTaskOwnership(req, res, id))) return;
+    try {
+      const url = await db.deleteTaskVisualSlot({ taskId: id, slot });
+      if (url) await visuals.deleteStored(url);
+      return res.json({ ok: true, slot, visual_url: null });
+    } catch (err) {
+      log.error({ taskId: id, slot, err: err && err.message }, 'task-visual slot delete failed');
+      return res.fail('visual_delete_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // GET /tasks/:id/visuals — the task's named visuals. Any signed-in builder: it
+  // lists URLs only, and each image is still served under its own task's audience.
+  router.get('/tasks/:id/visuals', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    try {
+      const task = await db.getTaskVisualAccess(id);
+      if (!task) return res.fail('task_not_found', 404);
+      const rows = await db.listTaskVisualSlots(id);
+      return res.json({ ok: true, task_id: String(id), slots: rows.map((x) => ({ slot: x.slot, visual_url: x.visual_url, visual_alt: x.visual_alt, updated_at: x.updated_at })) });
+    } catch (err) {
+      log.error({ taskId: id, err: err && err.message }, 'task-visual slot list failed');
+      return res.fail('visual_list_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // DELETE /tasks/:id/visual — remove it again. The counterpart to "always
   // optional": a builder who attached the wrong screenshot must be able to take
   // it back, and an image is not prose (the write-once rule of task 1003102

package/modules/lifecycle/task-visual-db.js

@@ -43,4 +43,43 @@ async function getTaskVisualAccess(taskId) {
   return rows[0] ?? null;
 }
 
-module.exports = { setTaskVisual, getTaskVisualAccess };
+// NAMED SLOTS (task 1004322, lifecycle_013). Status-blind, like the two above:
+// the routes decide who may write and who may see.
+//
+// Upsert one slot. Returns the stored row and the URL it REPLACED (null when the
+// slot was empty), read in the same statement so the route can unlink exactly the
+// superseded file.
+async function setTaskVisualSlot({ taskId, slot, visualUrl, visualAlt = null }) {
+  const { rows } = await pool.query(
+    `WITH prev AS (
+       SELECT visual_url FROM lifecycle_task_visual_slots WHERE task_id = $1 AND slot = $2
+     )
+     INSERT INTO lifecycle_task_visual_slots (task_id, slot, visual_url, visual_alt, updated_at)
+     VALUES ($1, $2, $3, $4, now())
+     ON CONFLICT (task_id, slot) DO UPDATE
+       SET visual_url = EXCLUDED.visual_url, visual_alt = EXCLUDED.visual_alt, updated_at = now()
+     RETURNING slot, visual_url, visual_alt, (SELECT visual_url FROM prev) AS replaced_url`,
+    [taskId, slot, visualUrl, visualAlt]
+  );
+  return rows[0] ?? null;
+}
+
+// Remove one slot. Returns the URL it held, or null when it was already empty.
+async function deleteTaskVisualSlot({ taskId, slot }) {
+  const { rows } = await pool.query(
+    `DELETE FROM lifecycle_task_visual_slots WHERE task_id = $1 AND slot = $2 RETURNING visual_url`,
+    [taskId, slot]
+  );
+  return rows[0] ? rows[0].visual_url : null;
+}
+
+// Every slot a task carries, by name.
+async function listTaskVisualSlots(taskId) {
+  const { rows } = await pool.query(
+    `SELECT slot, visual_url, visual_alt, updated_at FROM lifecycle_task_visual_slots WHERE task_id = $1 ORDER BY slot`,
+    [taskId]
+  );
+  return rows;
+}
+
+module.exports = { setTaskVisual, getTaskVisualAccess, setTaskVisualSlot, deleteTaskVisualSlot, listTaskVisualSlots };

package/modules/lifecycle/task-visuals.js

@@ -55,6 +55,24 @@ const TYPE_BY_EXT = {
 };
 
 const MAX_BYTES = 4 * 1024 * 1024; // 4 MB — a screenshot, not an asset library.
+
+// NAMED SLOTS (task 1004322 / BV2.TW11, lifecycle_013). A task may carry named
+// visuals beside its one ship-time picture. The shape is the column's own CHECK,
+// restated so a bad name is refused before any byte is stored.
+const SLOT_RE = /^[a-z0-9]+(-[a-z0-9]+){0,5}$/;
+const MAX_SLOT_LENGTH = 48;
+function isSafeSlot(slot) {
+  return typeof slot === 'string' && slot.length <= MAX_SLOT_LENGTH && SLOT_RE.test(slot);
+}
+// The eight renders /tweak attaches to a page tweak (ADR 0341 D7, builder pick 9):
+// the applied page before and after, desktop (1440) and phone (390), light and
+// dark. Declared ONCE: the renderer names its files with it, the attach step
+// uploads by it, and the Approval queue (TW12) reads the same names.
+const TWEAK_RENDER_PHASES = Object.freeze(['before', 'after']);
+const TWEAK_RENDER_DEVICES = Object.freeze({ desktop: 1440, phone: 390 });
+const TWEAK_RENDER_MODES = Object.freeze(['light', 'dark']);
+const TWEAK_RENDER_SLOTS = Object.freeze(TWEAK_RENDER_PHASES.flatMap((phase) =>
+  Object.keys(TWEAK_RENDER_DEVICES).flatMap((device) => TWEAK_RENDER_MODES.map((mode) => `${phase}-${device}-${mode}`))));
 const MAX_ALT_LENGTH = 300;        // the caption/alt text stored beside it.
 
 // Stored filenames are SERVER-generated, never user-supplied: a fixed shape we
@@ -249,6 +267,12 @@ async function deleteStored(nameOrUrl, { dir = visualsDir() } = {}) {
 }
 
 module.exports = {
+  isSafeSlot,
+  MAX_SLOT_LENGTH,
+  TWEAK_RENDER_PHASES,
+  TWEAK_RENDER_DEVICES,
+  TWEAK_RENDER_MODES,
+  TWEAK_RENDER_SLOTS,
   EXT_BY_TYPE,
   TYPE_BY_EXT,
   MAX_BYTES,

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1062",
+  "version": "1.19.1064",
   "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

@@ -7673,5 +7673,17 @@
       "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,"
     }
+  ],
+  "1.19.1063": [
+    {
+      "id": "1004321",
+      "text": "Artists now have their own editor for a page. It shows every word of the page as one sheet of paper over the studio at night. You type over any line and it saves as you go. A changed line gets a small orange mark and shows wha"
+    }
+  ],
+  "1.19.1064": [
+    {
+      "id": "1004322",
+      "text": "A session can now apply an artist's rewritten page. The new /tweak skill takes the next submitted page, applies every line in one pass, and photographs the page before and after, on a desktop and a phone, in light and dark, at"
+    }
   ]
 }