@bongos/core 1.19.922 → 1.19.924

package/tests/idea_state.mjs

@@ -0,0 +1,399 @@
+// tests/idea_state.mjs
+//
+// task 1004103 (BV2.R17, goal 1000095, criterion `ideator-sky-tells-the-truth`)
+// — THE FIVE STATES resolve from ledger facts. Spec
+// docs/specs/bongos-v2-ideator-surface.md decisions 4, 19 and 20; the object
+// vocabulary is docs/design/ideator-surface-direction.md §"The five objects".
+//
+// WHAT CAN GO SILENTLY WRONG HERE, which is what this file is aimed at:
+//
+//   * A PROTOSTAR DRAWN AS A REMNANT. An idea that has earned nothing comes back
+//     from brightness as `share: 1, hasWork: false` — LIT. Resolve the state off
+//     the share alone and a freshly-filed thought is indistinguishable from one
+//     whose version the project tore out, which is the exact distinction the two
+//     channels exist to draw. §2.
+//   * "COULD NOT LOOK" READ AS "EVERYTHING WAS REMOVED". `share: null` means the
+//     removal facts were unreadable, not that nothing survived. A resolver that
+//     treats a falsy share as dead turns one unmounted module into a sky of
+//     hollow rings. §3.
+//   * A COLD BODY WITH MONEY ON IT. The design defines a cold body as having no
+//     size at all; triage can discard a duplicate whose twin already paid, so
+//     the property only holds if work is tested BEFORE the status. §4.
+//   * A MERGED THOUGHT DRAWN TWICE. It keeps its own size (trail-size.js is
+//     emphatic), so an order that lets work win would draw a satellite as an
+//     independent star beside the thought that absorbed it. §5.
+//   * THE WELL READ OFF THE HINT. `suggested_goal_id` names a goal and is
+//     strictly advisory — the routing hint on a filing that did NOT convert. Read
+//     it as a home and a protostar joins a nod queue nobody can act on, because
+//     no task exists to promote. §6.
+//   * THE BINDING FACT NEVER REACHING THE RESOLVER. The state can only tell a
+//     well from open space if the trail actually selects `goal_id`; drop it and
+//     every thought in the instance quietly reads as homeless. §7 reads the
+//     statement.
+//   * THE ATTACH NEVER BEING CALLED. A resolver nothing invokes passes its whole
+//     suite and reaches no surface — this module's own history (a dead cascade
+//     rule) says so. §8 drives the real attacher and §9 holds the route wiring.
+//   * THE PAGE PAYING TWICE. Brightness takes its share of the same `byTask`
+//     breakdown size already computed; not handing it back doubles the ledger
+//     reads on every trail view, with nothing rendering differently. §8.
+//
+// DB-free: the reward port is a stub and the resolver is pure.
+//
+// Run:  node tests/idea_state.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const api = require('../src/module-api.js');
+const state = require('../modules/ideas/idea-state.js');
+const reward = require('../modules/economy/reward.js');
+
+const { resolveIdeaState, taskFactsFromIdeaRow, attachStateToTrail, IDEA_STATES, IDEA_POSITIONS } = state;
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed += 1; console.log(`ok   ${name}`); }
+  catch (err) { failed += 1; console.log(`FAIL ${name}\n     ${err && (err.message || JSON.stringify(err))}`); }
+}
+
+// A lit idea that has been paid: what brightness returns for a live descent.
+const LIVE = { hasWork: true, share: 1, attributable: true };
+// The same descent, every piece of it confirmed removed.
+const DEAD = { hasWork: true, share: 0, attributable: true };
+// A thought that has earned nothing — LIT, because nothing has been taken away.
+const UNIGNITED = { hasWork: false, share: 1, attributable: true };
+
+// ---------------------------------------------------------------------------
+// 1. the five objects, each from its facts
+// ---------------------------------------------------------------------------
+
+await test('§1 star — it caused work that is still alive', () => {
+  const s = resolveIdeaState({ status: 'promoted', ...LIVE });
+  assert.equal(s.state, IDEA_STATES.STAR);
+  assert.equal(s.brightness, 1);
+});
+
+await test('§1 star — partly removed is DIM, not out', () => {
+  const s = resolveIdeaState({ status: 'promoted', hasWork: true, share: 0.4, attributable: true });
+  assert.equal(s.state, IDEA_STATES.STAR, 'graded, not binary — it goes out only when nothing survives');
+  assert.equal(s.brightness, 0.4, 'and the surface reads the dimness off the same answer');
+});
+
+await test('§1 protostar — filed, not yet ignited', () => {
+  assert.equal(resolveIdeaState({ status: 'open', ...UNIGNITED }).state, IDEA_STATES.PROTOSTAR);
+});
+
+await test('§1 protostar — PROMOTED but unshipped is still unignited', () => {
+  // Ignition is being paid for something, not being converted into a row. A
+  // status-first resolver calls this a star and the sky claims work that has not
+  // happened.
+  const s = resolveIdeaState({
+    status: 'promoted', ...UNIGNITED,
+    tasks: [{ taskId: '5', goalId: '9', status: 'ready' }],
+  });
+  assert.equal(s.state, IDEA_STATES.PROTOSTAR);
+});
+
+await test('§1 satellite — folded into another thought', () => {
+  assert.equal(resolveIdeaState({ status: 'merged', ...UNIGNITED }).state, IDEA_STATES.SATELLITE);
+});
+
+await test('§1 remnant — it burned, then the project removed it', () => {
+  const s = resolveIdeaState({ status: 'promoted', ...DEAD });
+  assert.equal(s.state, IDEA_STATES.REMNANT);
+  assert.equal(s.hasWork, true, 'and it KEEPS its size — large and dead is the whole point');
+});
+
+await test('§1 cold body — declined at triage, having caused nothing', () => {
+  const s = resolveIdeaState({ status: 'discarded', ...UNIGNITED });
+  assert.equal(s.state, IDEA_STATES.COLD_BODY);
+  assert.equal(s.hasWork, false);
+});
+
+// ---------------------------------------------------------------------------
+// 2. zero over zero — the sharpest edge brightness hands over
+// ---------------------------------------------------------------------------
+
+await test('§2 an idea that earned nothing is a PROTOSTAR, never a remnant', () => {
+  // brightness returns share 1 / hasWork false for it on purpose. The failure
+  // this pins is a resolver that asks "is the share zero" of an idea whose share
+  // was never a fraction of anything.
+  const fresh = resolveIdeaState({ status: 'open', hasWork: false, share: 1, attributable: true });
+  const torn = resolveIdeaState({ status: 'promoted', hasWork: true, share: 0, attributable: true });
+  assert.equal(fresh.state, IDEA_STATES.PROTOSTAR);
+  assert.equal(torn.state, IDEA_STATES.REMNANT);
+  assert.notEqual(fresh.state, torn.state, 'these two must never be the same object');
+});
+
+await test('§2 hasWork is what separates them, not the share', () => {
+  // Same share on both sides; only hasWork differs.
+  const a = resolveIdeaState({ status: 'open', hasWork: false, share: 0, attributable: true });
+  const b = resolveIdeaState({ status: 'open', hasWork: true, share: 0, attributable: true });
+  assert.equal(a.state, IDEA_STATES.PROTOSTAR);
+  assert.equal(b.state, IDEA_STATES.REMNANT);
+});
+
+// ---------------------------------------------------------------------------
+// 3. a remnant needs EVIDENCE of removal, never the absence of an answer
+// ---------------------------------------------------------------------------
+
+await test('§3 unreadable removal facts give a STAR, flagged unattributable', () => {
+  const s = resolveIdeaState({ status: 'promoted', hasWork: true, share: null, attributable: false });
+  assert.equal(s.state, IDEA_STATES.STAR, 'we could not look — that is not evidence the work is gone');
+  assert.equal(s.attributable, false, 'and the surface is TOLD, so it can say "unknown" rather than "full"');
+  assert.equal(s.brightness, null);
+});
+
+await test('§3 a share of 0 with attributable false is still not a remnant', () => {
+  // Defensive: brightness never emits this pair, and a resolver that reads the
+  // share without the flag would call an unreadable idea dead the day it did.
+  const s = resolveIdeaState({ status: 'promoted', hasWork: true, share: 0, attributable: false });
+  assert.equal(s.state, IDEA_STATES.STAR);
+});
+
+// ---------------------------------------------------------------------------
+// 4. work beats a discard — the cold body's stated property
+// ---------------------------------------------------------------------------
+
+await test('§4 a DISCARDED idea that caused paid work is not a cold body', () => {
+  // Reachable: triage discards a duplicate whose twin already routed and paid,
+  // and updateIdea never touches the ledger. A cold body "has no size at all" —
+  // testing work first is what keeps that true by construction.
+  const s = resolveIdeaState({ status: 'discarded', ...LIVE });
+  assert.equal(s.state, IDEA_STATES.STAR);
+});
+
+await test('§4 a discarded idea whose work was then removed is a remnant', () => {
+  assert.equal(resolveIdeaState({ status: 'discarded', ...DEAD }).state, IDEA_STATES.REMNANT);
+});
+
+// ---------------------------------------------------------------------------
+// 5. merged wins over everything — one thought, one point in the sky
+// ---------------------------------------------------------------------------
+
+await test('§5 a MERGED idea with money of its own is still a satellite', () => {
+  // It keeps its own size (trail-size.js), and that stays true — this changes
+  // what the thought IS, not what it earned. Letting work win here draws it as an
+  // independent star beside the thought that absorbed it.
+  const s = resolveIdeaState({ status: 'merged', ...LIVE });
+  assert.equal(s.state, IDEA_STATES.SATELLITE);
+  assert.equal(s.hasWork, true, 'and its size is reported, not erased');
+});
+
+await test('§5 a merged idea whose work was removed is a satellite too', () => {
+  assert.equal(resolveIdeaState({ status: 'merged', ...DEAD }).state, IDEA_STATES.SATELLITE);
+});
+
+// ---------------------------------------------------------------------------
+// 6. position — the distinction the object alone cannot carry
+// ---------------------------------------------------------------------------
+
+await test('§6 a protostar in a WELL awaits a nod', () => {
+  const s = resolveIdeaState({
+    status: 'open', ...UNIGNITED,
+    tasks: [{ taskId: '5', goalId: '77', status: 'backlog' }],
+  });
+  assert.equal(s.position, IDEA_POSITIONS.WELL);
+  assert.equal(s.wellGoalId, '77');
+  assert.equal(s.awaitingNod, true, 'this is what makes the nod queue something a person can SEE');
+});
+
+await test('§6 a protostar in OPEN SPACE has nothing holding it', () => {
+  const s = resolveIdeaState({ status: 'open', ...UNIGNITED, tasks: [] });
+  assert.equal(s.position, IDEA_POSITIONS.OPEN_SPACE);
+  assert.equal(s.wellGoalId, null);
+  assert.equal(s.awaitingNod, false);
+});
+
+await test('§6 suggested_goal_id is a HINT and never a well', () => {
+  // It names a goal and it is strictly advisory: the routing hint on a filing
+  // that did not convert. Reading it here puts a thought in a nod queue with no
+  // task to promote.
+  const row = { id: '1', status: 'open', suggested_goal_id: '77', lineage_tasks: [] };
+  const s = resolveIdeaState({ status: row.status, ...UNIGNITED, tasks: taskFactsFromIdeaRow(row) });
+  assert.equal(s.position, IDEA_POSITIONS.OPEN_SPACE);
+  assert.equal(s.wellGoalId, null);
+});
+
+await test('§6 a task in a goal that is past the nod is a well, not a queue', () => {
+  const s = resolveIdeaState({
+    status: 'promoted', ...LIVE,
+    tasks: [{ taskId: '5', goalId: '77', status: 'shipped' }],
+  });
+  assert.equal(s.position, IDEA_POSITIONS.WELL);
+  assert.equal(s.awaitingNod, false);
+});
+
+await test('§6 the nod is asked of EVERY task, not only the one that named the well', () => {
+  // One idea, two tasks: one promoted, one still at backlog. Something still
+  // awaits a person, and a resolver that only inspected the first task misses it.
+  const s = resolveIdeaState({
+    status: 'promoted', ...LIVE,
+    tasks: [
+      { taskId: '5', goalId: '77', status: 'ready' },
+      { taskId: '6', goalId: '77', status: 'backlog' },
+    ],
+  });
+  assert.equal(s.awaitingNod, true);
+});
+
+await test('§6 a backlog task with NO goal is not a nod queue entry', () => {
+  // The nod is a promote within a goal; a goal-less backlog row has no well to
+  // be promoted inside.
+  const s = resolveIdeaState({
+    status: 'open', ...UNIGNITED,
+    tasks: [{ taskId: '5', goalId: null, status: 'backlog' }],
+  });
+  assert.equal(s.awaitingNod, false);
+  assert.equal(s.position, IDEA_POSITIONS.OPEN_SPACE);
+});
+
+// ---------------------------------------------------------------------------
+// 7. the facts off a real trail row — and the statement that carries them
+// ---------------------------------------------------------------------------
+
+await test('§7 lineage tasks and the legacy column are BOTH read, and never twice', () => {
+  // lineage_tasks is the complete answer since ideas_task_lineage; the legacy
+  // promoted_to_task_id is the only answer for promotions that predate it. An
+  // idea carrying both must not count that task twice.
+  const both = taskFactsFromIdeaRow({
+    promoted_to_task_id: '5', promoted_task_status: 'ready', promoted_task_goal_id: '77',
+    lineage_tasks: [{ task_id: 5, status: 'ready', goal_id: 77 }],
+  });
+  assert.equal(both.length, 1, 'the same task named twice is one task');
+  const legacyOnly = taskFactsFromIdeaRow({
+    promoted_to_task_id: '5', promoted_task_status: 'backlog', promoted_task_goal_id: '77',
+    lineage_tasks: [],
+  });
+  assert.equal(legacyOnly.length, 1);
+  assert.equal(legacyOnly[0].goalId, '77', 'a pre-lineage promotion still has a home');
+});
+
+await test('§7 ids survive as strings — a bigint is never coerced', () => {
+  const facts = taskFactsFromIdeaRow({ lineage_tasks: [{ task_id: 9007199254740993, goal_id: '77', status: 'ready' }] });
+  assert.equal(facts[0].goalId, '77');
+  assert.equal(typeof facts[0].taskId, 'string');
+});
+
+await test('§7 the trail SELECTS goal_id on both task joins', () => {
+  // The binding fact. Without it every thought reads as homeless and the
+  // well-vs-open-space distinction silently disappears — nothing errors, the
+  // nod queue is simply empty forever.
+  const sql = fs.readFileSync(path.join(ROOT, 'modules/ideas/trail.js'), 'utf8');
+  assert.match(sql, /'goal_id',\s*lt\.goal_id/, 'the lineage LATERAL must carry the goal');
+  assert.match(sql, /pt\.goal_id\s+AS\s+promoted_task_goal_id/, 'and so must the legacy join');
+});
+
+// ---------------------------------------------------------------------------
+// 8. the attach — including the branch where the reward port is not there
+// ---------------------------------------------------------------------------
+
+await test('§8 with the reward port absent, the states still resolve — flagged', () => {
+  // Run before the port is registered: a port is single-provider and cannot be
+  // unregistered, so this is the only honest place for the absent branch. An
+  // unmounted economy must not empty the sky.
+  assert.equal(api.hasProvider('reward'), false, 'nothing has registered it yet');
+  return attachStateToTrail([{ id: '7', status: 'open', lineage_tasks: [] }]).then((ideas) => {
+    assert.equal(ideas[0].state.state, IDEA_STATES.PROTOSTAR);
+    assert.equal(ideas[0].state.attributable, false, 'the money could not be read, and it says so');
+  });
+});
+
+// The port stub. It records what it was ASKED, which is what §8's one-read
+// property is pinned on.
+const asked = [];
+api.registerProvider('reward', {
+  ...reward,
+  async ideaBrightnesses(ids, opts = {}) {
+    asked.push({ ids: ids.map(String), sizes: opts.sizes || null });
+    const out = new Map();
+    for (const id of ids.map(String)) {
+      if (id === '7') out.set(id, { ...LIVE, credits: 40, removedTasks: [] });
+      if (id === '8') out.set(id, { ...DEAD, credits: 40, removedTasks: [{ taskId: '500', credits: 40 }] });
+      if (id === '9') out.set(id, { ...UNIGNITED, credits: 0, removedTasks: [] });
+    }
+    return out;
+  },
+});
+
+await test('§8 the attach hangs one state per idea, off the real brightness', async () => {
+  const ideas = [
+    { id: '7', status: 'promoted', lineage_tasks: [{ task_id: 500, goal_id: 77, status: 'shipped' }] },
+    { id: '8', status: 'promoted', lineage_tasks: [{ task_id: 500, goal_id: 77, status: 'shipped' }] },
+    { id: '9', status: 'open', lineage_tasks: [] },
+  ];
+  await attachStateToTrail(ideas);
+  assert.equal(ideas[0].state.state, IDEA_STATES.STAR);
+  assert.equal(ideas[1].state.state, IDEA_STATES.REMNANT);
+  assert.equal(ideas[2].state.state, IDEA_STATES.PROTOSTAR);
+  assert.equal(ideas[2].state.position, IDEA_POSITIONS.OPEN_SPACE);
+});
+
+await test('§8 an already-computed size is HANDED BACK, so the page reads once', async () => {
+  // attachSizeToTrail leaves economy's own byTask breakdown on the row, and
+  // brightness takes its share of exactly that. Not passing it makes every trail
+  // view pay for the ledger twice, and nothing renders differently.
+  asked.length = 0;
+  const withSize = [
+    { id: '7', status: 'promoted', lineage_tasks: [], size: { credits: 40, byTask: new Map([['500', 40]]) } },
+  ];
+  await attachStateToTrail(withSize);
+  assert.ok(asked[0].sizes instanceof Map, 'the breakdown must travel with the request');
+  assert.equal(asked[0].sizes.get('7').credits, 40);
+
+  // And a page where the sizes are NOT all in hand asks for none of them, rather
+  // than handing over a partial map: brightness reads a missing entry as "no
+  // work", which would draw a paid star as a protostar.
+  asked.length = 0;
+  await attachStateToTrail([
+    { id: '7', status: 'promoted', lineage_tasks: [], size: { credits: 40, byTask: new Map() } },
+    { id: '8', status: 'promoted', lineage_tasks: [], size: null },
+  ]);
+  assert.equal(asked[0].sizes, null, 'all of them or none — a partial map silently unlights a star');
+});
+
+await test('§8 an empty page costs nothing at all', async () => {
+  asked.length = 0;
+  assert.deepEqual(await attachStateToTrail([]), []);
+  assert.equal(asked.length, 0);
+});
+
+// ---------------------------------------------------------------------------
+// 9. the wiring — a resolver nothing calls reaches no surface
+// ---------------------------------------------------------------------------
+
+await test('§9 the trail route attaches the state, AFTER the size', async () => {
+  const route = fs.readFileSync(path.join(ROOT, 'modules/ideas/routes/inbox.js'), 'utf8');
+  assert.match(route, /require\('\.\.\/idea-state'\)/, 'the route must import it');
+  const size = route.indexOf('await attachSizeToTrail(ideas)');
+  const stateAt = route.indexOf('await attachStateToTrail(ideas)');
+  assert.ok(size > 0 && stateAt > 0, 'both attaches must be called on the trail');
+  assert.ok(stateAt > size, 'state reads the byTask breakdown size leaves behind, so it runs second');
+});
+
+await test('§9 the reward port exposes brightness at all', async () => {
+  // The ideas module may only reach credit_log through this port (ADR 0083 rule
+  // 1). Shipping brightness without putting it on the port leaves the module able
+  // to draw how big a thought is and unable to say whether it is still alive.
+  assert.equal(typeof reward.ideaBrightnesses, 'function');
+  assert.equal(typeof reward.ideaBrightness, 'function');
+});
+
+await test('§9 the five objects are spelled ONCE, and the module exports them', async () => {
+  // A renderer switching on hand-copied strings drifts by a hyphen and draws
+  // nothing, silently.
+  assert.deepEqual(
+    [...state.IDEA_STATE_VALUES].sort(),
+    ['cold-body', 'protostar', 'remnant', 'satellite', 'star']
+  );
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);