@bongos/core 1.19.1057 → 1.19.1058

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

@@ -0,0 +1,87 @@
+// modules/lifecycle/page-tweak-reads.js — the two ledger reads Tweak Mode's
+// status, changelog, drift and tally are derived from (task 1004316 / BV2.TW05,
+// ADR 0341 D7, D8, D10). Read-only; no state transition lives here.
+//
+// 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). The
+// derivation itself is copy-desk's (modules/copy-desk/page-status.js); these
+// return the rows it reads, column for column, with no projection in between,
+// so a field added here reaches the derivation without a second mapper to
+// forget.
+
+'use strict';
+
+const api = require('../../src/module-api');
+
+// Every page-tweak task, oldest first, with what the round state (D7) and the
+// changelog (D8) need beside the task itself:
+//
+//   grade_passed      the task's grade (task_grades holds one row per task, the
+//                     latest). A completed round with a passed grade is waiting
+//                     for the artist; with a failed one it is still applying.
+//   holder_*          the ACTIVE claim, if any. holder_worktree is true for a CLI
+//                     claim (a worktree: the applier) and false for a web claim
+//                     (bind_session=false, no worktree: the artist writing).
+//   artist_*          the round's artist, the payee rule of D10: the builder of
+//                     the latest WEB claim on the task, which is the one the
+//                     submit released. Never a field in the description, which
+//                     the task's editors could change.
+//
+// THE QUERY PLAN, since this read backs all three page routes:
+//   * `t.source = 'page-tweak'` is served by idx_tasks_source_ref, which leads
+//     on (source) (migrations/core_240_artist_gate_indexes.sql), so the scan is
+//     bounded to the page-tweak rows, not the whole task table.
+//   * the active claim is a plain join: uniq_active_claim_per_task allows at
+//     most one row per task, and its partial index serves it.
+//   * the latest web claim is ONE pass over claims (the `web` CTE, DISTINCT ON
+//     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() {
+  const { rows } = await api.pool.query(
+    `WITH pt AS (
+       SELECT t.id FROM tasks t WHERE t.source = 'page-tweak'
+     ), 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
+        WHERE c.worktree_name IS NULL AND c.creator_session_id IS NULL
+        ORDER BY c.task_id, c.claimed_at DESC, c.id DESC
+     )
+     SELECT t.id, t.status, t.title, t.description, t.source_ref, t.touches,
+            t.shipped_at, t.created_at, t.updated_at,
+            g.passed AS grade_passed,
+            ac.builder_id AS holder_id, hb.github_login AS holder_login,
+            (ac.worktree_name IS NOT NULL) AS holder_worktree,
+            wc.builder_id AS artist_id, ab.github_login AS artist_login
+       FROM tasks t
+       LEFT JOIN task_grades g ON g.task_id = t.id
+       LEFT JOIN claims ac ON ac.task_id = t.id AND ac.released_at IS NULL
+       LEFT JOIN builders hb ON hb.id = ac.builder_id
+       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`
+  );
+  return rows;
+}
+
+// The ships that changed a page since its last round (D8): shipped tasks after
+// `since` whose touches meet the page's files. The array-overlap operator is the
+// same one the parallel-safety check uses, served by idx_tasks_touches_gin.
+async function shippedTasksTouchingSince({ files, since, limit = 50 } = {}) {
+  const list = Array.isArray(files) ? files.map(String).filter(Boolean) : [];
+  if (!list.length || !since) return [];
+  const { rows } = await api.pool.query(
+    `SELECT t.id, t.title, t.shipped_at
+       FROM tasks t
+      WHERE t.status = 'shipped'
+        AND t.shipped_at > $2::timestamptz
+        AND t.touches && $1::text[]
+      ORDER BY t.shipped_at ASC, t.id ASC
+      LIMIT $3`,
+    [list, since, Math.max(1, Math.min(200, Number(limit) || 50))]
+  );
+  return rows;
+}
+
+module.exports = { listPageTweakTasks, shippedTasksTouchingSince };

package/package-lock.json

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

package/package.json

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

@@ -7643,5 +7643,11 @@
       "id": "1004315",
       "text": "Every page of the project now has a written reading: all the words it actually shows, in order, grouped under its headings. Each line says where the words live. Some come from a known place in the code, some are shared by ever"
     }
+  ],
+  "1.19.1058": [
+    {
+      "id": "1004316",
+      "text": "Every page now has a status that is worked out from the project's own record, with nothing new to keep in sync. For each page you can see whether it is untweaked or text tweaked and how many times, a history of each round (who"
+    }
   ]
 }

package/scripts/gds/publish-manifest.js

@@ -124,6 +124,13 @@ const PUBLISH_ALLOWLIST = [
   // only because that is where their generator has always written them.
   'docs/copy-registry.json',
   'docs/copy-inventory.md',          // the human twin, generated in the same pass
+  // Tweak Mode's two page artifacts (ADR 0341 D1, task 1004316), the same kind
+  // of runtime data: modules/copy-desk/page-data.js reads both on every page
+  // status read, and neither generator can run on a deployed box (the reader
+  // opens a browser against a source tree). Without the inventory an instance
+  // answers 503 page_inventory_missing; without the readings drift reads unknown.
+  'docs/page-inventory.json',
+  'docs/page-readings.json',
   'docs/file-map.md',
   'docs/repo-map.md',
   'docs/handoff-template.md',         // the portable session-handoff format (methodology)

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.1057'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1058'; // 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');

package/tests/copy_desk_page_reads.mjs

@@ -0,0 +1,194 @@
+// tests/copy_desk_page_reads.mjs — Tweak Mode's three reads, the WHOLE path
+// (task 1004316 / BV2.TW05, ADR 0341 D1, D8, D11).
+//
+// modules/copy-desk/tests/copy_page_status.mjs proves the derivation on
+// hand-shaped rows. This proves the path those rows actually travel: the real
+// lifecycle port's SQL (listPageTweakTasks, shippedTasksTouchingSince) and the
+// real reward port's creditLedger, answered by a fake pool, through the real
+// copy-desk routes and the real error envelope, reading the page artifacts from
+// disk through page-data.js. A field the SQL names and the derivation does not
+// read (or the reverse) reds here and nowhere else.
+//
+// And the degrade (ADR 0341 D1): an instance with no page inventory answers a
+// named 503 carrying the generator command, never a crash, while the tally,
+// which needs no inventory, still answers; an instance with the inventory but
+// no readings still reports status and marks drift unknown.
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { makeRunner } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+
+const F = require('../modules/copy-desk/tests/fixtures/page-tweak.cjs');
+const api = require('../src/module-api.js');
+
+// The fake pool, dispatching on the SQL each port read sends. Installed BEFORE
+// the ports are required: economy/credits.js destructures the pool at load.
+const seen = [];
+const flat = (sql) => String(sql).replace(/\s+/g, ' ').trim();
+api.pool = {
+  async query(sql, params = []) {
+    const q = flat(sql);
+    seen.push({ q, params });
+    if (/FROM tasks t LEFT JOIN task_grades g/.test(q)) {
+      assert.match(q, /WHERE t\.source = 'page-tweak'/);
+      // The fixture rows stand in for this SELECT, so every column they carry
+      // must be one the SELECT really names: a renamed alias would otherwise
+      // leave the fake answering with a field the real query never returns.
+      const select = q.slice(q.indexOf(') SELECT '), q.indexOf(' FROM tasks t LEFT JOIN'));
+      // One pass over claims for the round's artist, never a per-task subquery.
+      assert.doesNotMatch(q, /LATERAL/);
+      for (const col of Object.keys(F.TASKS[0])) {
+        assert.match(select, new RegExp(`(?:t\\.${col}\\b|AS ${col}\\b)`), `the SELECT must name ${col}`);
+      }
+      return { rows: F.TASKS };
+    }
+    if (/t\.touches && \$1::text\[\]/.test(q)) {
+      return { rows: F.STUDIO_SHIPS.filter((s) => new Date(s.shipped_at) > new Date(params[1])) };
+    }
+    if (/FROM credit_log/.test(q)) {
+      const prefix = String(params[1] || '').replace(/%$/, '').replace(/\\([\\%_])/g, '$1');
+      const rows = F.CREDIT_ROWS
+        .filter((r) => String(r.builder_id) === String(params[0]) && r.reason.startsWith(prefix))
+        .map((r) => ({ ...r }));
+      return { rows: rows.map((r, _, all) => ({ ...r, total_count: all.length })) };
+    }
+    throw new Error(`unexpected SQL in the page reads: ${q.slice(0, 120)}`);
+  },
+};
+
+// Sign-in is the one thing stubbed: the caller is whoever the header names.
+api.requireBuilder = (req, res, next) => {
+  req.builder = { id: String(req.headers['x-builder'] || F.ALICE.id), rank: 'thetes' };
+  next();
+};
+
+const seams = require('../src/module-seams.js');
+if (!seams.hasProvider('lifecycle')) seams.registerProvider('lifecycle', require('../modules/lifecycle/lifecycle.js'));
+if (!seams.hasProvider('reward')) seams.registerProvider('reward', require('../modules/economy/reward.js'));
+
+const pageData = require('../modules/copy-desk/page-data.js');
+const express = require('express');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+const buildRouter = require('../modules/copy-desk/routes/copy-desk.js');
+
+const app = express();
+app.use(attachFail);
+app.use(buildRouter());
+const server = await new Promise((resolve) => { const s = app.listen(0, '127.0.0.1', () => resolve(s)); });
+const base = `http://127.0.0.1:${server.address().port}`;
+
+async function get(p, builder) {
+  const r = await fetch(base + p, { headers: builder ? { 'x-builder': builder } : {} });
+  return { status: r.status, body: await r.json() };
+}
+
+// Three roots: both artifacts, the inventory alone, and nothing at all.
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'page-reads-'));
+const root = (name, files) => {
+  const dir = path.join(tmp, name);
+  fs.mkdirSync(path.join(dir, 'docs'), { recursive: true });
+  for (const [rel, v] of Object.entries(files)) fs.writeFileSync(path.join(dir, rel), JSON.stringify(v));
+  return dir;
+};
+const FULL = root('full', { 'docs/page-inventory.json': F.INVENTORY, 'docs/page-readings.json': F.READINGS });
+const INV_ONLY = root('inventory-only', { 'docs/page-inventory.json': F.INVENTORY });
+const EMPTY = root('empty', {});
+
+const { test, summary } = makeRunner();
+
+try {
+  pageData._setRoot(FULL);
+
+  await test('GET /copy-desk/pages: the three fixture cases, and the per-surface rollup', async () => {
+    const { status, body } = await get('/copy-desk/pages');
+    assert.equal(status, 200);
+    const p = (id) => body.pages.find((x) => x.id === id);
+    assert.equal(p('landing:index').status_label, 'Untweaked');
+    assert.equal(p('landing:projects').status_label, 'Text tweaked 2x');
+    assert.equal(p('landing:projects').drift.changed, false);
+    assert.equal(p('builders:studio').status_label, 'Text tweaked 1x');
+    assert.equal(p('builders:studio').drift.changed_count, 1);
+    assert.equal(p('builders:studio').open_round.state, 'writing');
+    assert.deepEqual(body.surfaces.map((s) => s.line), ['1 of 2 tweaked', '1 of 1 tweaked', '0 of 1 tweaked']);
+    assert.deepEqual(body.readings, { ok: true, at: 'docs/page-readings.json' });
+    assert.deepEqual(body.inventory, { at: 'docs/page-inventory.json' });
+  });
+
+  await test('GET /copy-desk/pages/:pageId: changelog, changed-since lines and the ships that changed them', async () => {
+    seen.length = 0;
+    const { status, body } = await get('/copy-desk/pages/builders:studio');
+    assert.equal(status, 200);
+    assert.deepEqual(body.changelog.map((c) => [c.task_id, c.artist.login, c.line_count]), [['201', 'alice', 1]]);
+    assert.deepEqual(body.drift.changed_lines, [{ key: 'L0002', section: 'greeting', text: 'Welcome back' }]);
+    assert.deepEqual(body.drift.ships.map((s) => s.task_id), ['555']);
+    assert.deepEqual(body.open_round.holder, { id: '8', login: 'bob' });
+    // The ships read is asked about THIS page's files, since THIS page's last round.
+    const ships = seen.find((s) => /t\.touches &&/.test(s.q));
+    assert.deepEqual(ships.params[0], F.STUDIO_FILES);
+    assert.equal(ships.params[1], '2026-09-20T10:00:00.000Z');
+
+    const twice = await get('/copy-desk/pages/landing:projects');
+    assert.deepEqual(twice.body.changelog.map((c) => c.artist.login), ['bob', 'alice']);
+    const untweaked = await get('/copy-desk/pages/landing:index');
+    assert.deepEqual([untweaked.body.count, untweaked.body.changelog.length, untweaked.body.drift.ships.length], [0, 0, 0]);
+  });
+
+  await test('an id the inventory does not know is unknown_page, never a blank page', async () => {
+    for (const id of ['landing:nope', 'not-an-id']) {
+      const { status, body } = await get(`/copy-desk/pages/${id}`);
+      assert.equal(status, 404, id);
+      assert.equal(body.error.code, 'unknown_page', id);
+    }
+  });
+
+  await test('GET /copy-desk/tally: the caller\'s own, through the reward port, 0 where no payout row exists yet', async () => {
+    seen.length = 0;
+    const alice = await get('/copy-desk/tally', F.ALICE.id);
+    assert.equal(alice.status, 200);
+    assert.equal(alice.body.credits, 60);
+    assert.equal(alice.body.pages_tweaked, 2);
+    assert.equal(alice.body.builder_id, '7');
+    assert.equal(alice.body.truncated, false);
+    const reads = seen.filter((s) => /FROM credit_log/.test(s.q));
+    assert.equal(reads.length, 1, 'one bounded ledger read, never a paging loop');
+    assert.equal(String(reads[0].params[0]), '7', 'the ledger is read for the CALLER');
+    const bob = await get('/copy-desk/tally', F.BOB.id);
+    assert.deepEqual([bob.body.credits, bob.body.this_week, bob.body.pages_tweaked], [0, 0, 1]);
+  });
+
+  await test('no readings: status still reads from the ledger, and drift says it does not know', async () => {
+    pageData._setRoot(INV_ONLY);
+    const { status, body } = await get('/copy-desk/pages');
+    assert.equal(status, 200);
+    assert.equal(body.readings.ok, false);
+    assert.equal(body.readings.code, 'page_readings_missing');
+    const studio = body.pages.find((x) => x.id === 'builders:studio');
+    assert.equal(studio.status_label, 'Text tweaked 1x');
+    assert.deepEqual([studio.drift.known, studio.drift.reason], [false, 'readings_missing']);
+  });
+
+  await test('no inventory: a named 503 with the command that fixes it, and the tally still answers', async () => {
+    pageData._setRoot(EMPTY);
+    for (const p of ['/copy-desk/pages', '/copy-desk/pages/landing:index']) {
+      const { status, body } = await get(p);
+      assert.equal(status, 503, p);
+      assert.equal(body.error.code, 'page_inventory_missing', p);
+      assert.equal(body.error.details.run, 'node scripts/gds/page-inventory.js', p);
+    }
+    const tally = await get('/copy-desk/tally', F.ALICE.id);
+    assert.equal(tally.status, 200);
+    assert.equal(tally.body.credits, 60);
+  });
+} finally {
+  pageData._setRoot(null);
+  server.close();
+  fs.rmSync(tmp, { recursive: true, force: true });
+}
+
+summary();