@bongos/core 1.19.1024 → 1.19.1025

package/tests/terms_acceptance.mjs

@@ -115,6 +115,18 @@ t('the acceptance the page promises is the one the code actually keeps', () => {
     'and that it is written once — the property the COALESCE below actually provides');
 });
 
+t('the page says which acceptances were given on a builder’s behalf, and that the record marks them (task 1003360)', () => {
+  assert.match(termsHtml, /accepted it on your behalf/i,
+    'the owner chose to grandfather AND to say so on the page — the page must tell a pre-existing builder what was recorded for them');
+  assert.match(termsHtml, /marks that acceptance as grandfathered/i,
+    'and that the record keeps it distinguishable from one they gave');
+  assert.match(termsHtml, /your own acceptance replaces it the next time you sign in/i,
+    'and what happens when they do sign in — the conflict branch below really does replace it');
+  assert.doesNotMatch(termsHtml, /written only by signing in/i,
+    'the page still says acceptance is written ONLY by signing in, which is false for every grandfathered account');
+  assert.doesNotMatch(stripApexOnly(termsHtml), /grandfathered/i, 'a claim about the platform record survived into a child project page');
+});
+
 t('the cross-project claim is apex-only — it never ships in a child project page', () => {
   const stripped = stripApexOnly(termsHtml);
   assert.doesNotMatch(stripped, /Your work across projects/,
@@ -139,20 +151,24 @@ t('the acceptance fragments refuse anything that is not a Postgres placeholder',
   }
 });
 
-t('the conflict fragment is COALESCE-shaped — the first acceptance is the one that stands', () => {
+t('the conflict fragment keeps the first acceptance, and replaces only a grandfather', () => {
   const set = acceptanceConflictSet('$5', '$6');
-  assert.match(set, /COALESCE\(platform_identity_accounts\.terms_accepted_at, now\(\)\)/,
+  const self = 'platform_identity_accounts.';
+  const replaces = `CASE WHEN $5::boolean AND ${self}terms_accepted_source = 'grandfathered'`;
+  assert.ok(set.includes(`terms_accepted_at = ${replaces} THEN now() WHEN $5::boolean THEN COALESCE(${self}terms_accepted_at, now()) ELSE ${self}terms_accepted_at END,`),
     'without COALESCE every sign-in restamps, and the record stops meaning "when you accepted"');
-  assert.match(set, /COALESCE\(platform_identity_accounts\.terms_version, \$6::text\)/);
-  assert.match(set, /ELSE platform_identity_accounts\.terms_accepted_at END/,
-    'a NON-activating upsert must leave the record exactly as it was');
+  assert.ok(set.includes(`terms_version = ${replaces} THEN $6::text WHEN $5::boolean THEN COALESCE(${self}terms_version, $6::text) ELSE ${self}terms_version END,`));
+  assert.ok(set.includes(`terms_accepted_source = CASE WHEN $5::boolean THEN 'signin' ELSE ${self}terms_accepted_source END,`),
+    'a sign-in is a human accepting: the source must say so, or a grandfather mark could outlive a real acceptance');
 });
 
-t('the insert fragment writes NULL for a caller the hub did not witness', () => {
+t('the insert fragment writes NULL for a caller the hub did not witness, and marks a witnessed one as a sign-in', () => {
   const values = acceptanceInsertValues('$5', '$6');
   assert.match(values, /CASE WHEN \$5::boolean THEN now\(\) ELSE NULL END/,
     'a check-in / device-poll account has no acceptance — fail-closed');
-  assert.equal(acceptanceInsertColumns(), ', terms_accepted_at, terms_version');
+  assert.match(values, /CASE WHEN \$5::boolean THEN 'signin' ELSE NULL END/,
+    'an acceptance written at sign-in must say so (task 1003360) — an unmarked one is indistinguishable from a grandfather');
+  assert.equal(acceptanceInsertColumns(), ', terms_accepted_at, terms_version, terms_accepted_source');
 });
 
 // ===========================================================================
@@ -183,10 +199,11 @@ function splitTopLevel(s) {
 // permissive `.*?` match: every shape this understands is spelled out, and an
 // unrecognised one THROWS. A SET list matched loosely is how a deleted audit
 // trail passes a test that looks like it is checking one.
-function evalAcceptance(expr, { col, activate, existing, params, now }) {
+function evalAcceptance(expr, { col, activate, existing, oldRow = {}, params, now }) {
   const self = `platform_identity_accounts.${col}`;
   const src = (tok) => {
     if (/^now\(\)$/i.test(tok)) return now;
+    if (tok === "'signin'") return 'signin';
     const m = /^\$(\d+)::text$/.exec(tok);
     if (m) return params[Number(m[1]) - 1];
     throw new Error(`unrecognised source expression "${tok}" for ${col}`);
@@ -194,7 +211,18 @@ function evalAcceptance(expr, { col, activate, existing, params, now }) {
   const esc = self.replace(/[.]/g, '\\.');
   let m;
 
-  // The shipped, idempotent shape: activate ? (existing ?? src) : existing
+  // The shipped shape (task 1003360): a grandfather is replaced, anything else is
+  // COALESCE'd. It reads the OLD row's source, as Postgres evaluates every SET
+  // right-hand side against the row before the update.
+  m = new RegExp(`^CASE WHEN \\$(\\d+)::boolean AND platform_identity_accounts\\.terms_accepted_source = 'grandfathered' THEN (.+?) WHEN \\$(\\d+)::boolean THEN COALESCE\\(${esc}, (.+?)\\) ELSE ${esc} END$`, 'i').exec(expr);
+  if (m) {
+    if (!activate) return existing;
+    if (oldRow.terms_accepted_source === 'grandfathered') return src(m[2]);
+    return existing != null ? existing : src(m[4]);
+  }
+
+  // The ADR 0213 shape: activate ? (existing ?? src) : existing. Recognised so a
+  // regression to it is caught by behaviour (a grandfather that never gives way).
   m = new RegExp(`^CASE WHEN \\$(\\d+)::boolean THEN COALESCE\\(${esc}, (.+?)\\) ELSE ${esc} END$`, 'i').exec(expr);
   if (m) return activate ? (existing != null ? existing : src(m[2])) : existing;
 
@@ -218,6 +246,9 @@ function evalAcceptance(expr, { col, activate, existing, params, now }) {
 
 const NOW = '2026-08-29T12:00:00.000Z';
 const LATER = '2026-08-30T09:30:00.000Z';
+const GRANDFATHERED_AT = '2026-08-29T00:00:00.000Z';
+// The three columns one acceptance writes (task 1003360 added the source).
+const ACCEPTANCE_COLUMNS = ['terms_accepted_at', 'terms_version', 'terms_accepted_source'];
 
 function makePool() {
   const accounts = new Map();      // github_id -> row
@@ -242,7 +273,7 @@ function makePool() {
         const existing = accounts.get(id);
 
         if (/ON CONFLICT \(github_id\) DO NOTHING/i.test(sql)) {
-          if (!existing) accounts.set(id, { github_id: id, github_login: params[1], profile_state: 'provisional', terms_accepted_at: null, terms_version: null, account_visibility: 'public', hide_stats: false, handle: 'h' });
+          if (!existing) accounts.set(id, { github_id: id, github_login: params[1], profile_state: 'provisional', terms_accepted_at: null, terms_version: null, terms_accepted_source: null, account_visibility: 'public', hide_stats: false, handle: 'h' });
           return { rows: [], rowCount: existing ? 0 : 1 };
         }
 
@@ -255,7 +286,7 @@ function makePool() {
         let row;
         if (!existing) {
           row = { github_id: id, github_login: params[1], account_visibility: 'public', hide_stats: false, handle: 'h' };
-          for (const col of ['terms_accepted_at', 'terms_version']) {
+          for (const col of ACCEPTANCE_COLUMNS) {
             const i = cols.indexOf(col);
             assert.notEqual(i, -1, `the upsert stopped writing ${col} on insert`);
             row[col] = evalAcceptance(values[i], { col, activate, existing: null, params, now: clock });
@@ -271,9 +302,10 @@ function makePool() {
             const eq = a.indexOf('=');
             assigns.set(a.slice(0, eq).trim(), a.slice(eq + 1).trim());
           }
-          for (const col of ['terms_accepted_at', 'terms_version']) {
+          const oldRow = { ...row };
+          for (const col of ACCEPTANCE_COLUMNS) {
             assert.ok(assigns.has(col), `the conflict branch stopped writing ${col} — an account that signs in again would never record its acceptance`);
-            row[col] = evalAcceptance(assigns.get(col), { col, activate, existing: row[col], params, now: clock });
+            row[col] = evalAcceptance(assigns.get(col), { col, activate, existing: oldRow[col], oldRow, params, now: clock });
           }
           if (activate) row.profile_state = 'active';
         }
@@ -375,6 +407,8 @@ await ta('CONTROL: a hub-session authorize records the acceptance', async () =>
   assert.ok(row, 'no account was written at all — the rest of this section would pass vacuously');
   assert.equal(row.terms_accepted_at, NOW, 'the acceptance was not stamped by the hub sign-in');
   assert.equal(row.terms_version, TERMS_VERSION, 'the record must name WHICH text was accepted');
+  assert.equal(row.terms_accepted_source, 'signin',
+    'and HOW it was given — a sign-in, queryably distinct from a grandfather (task 1003360)');
   assert.equal(row.profile_state, 'active');
 });
 
@@ -389,12 +423,13 @@ await ta('the acceptance cannot be forged from the query string or the body', as
   const res = await request(
     `/sso/authorize?client_id=proj-a&redirect_uri=${encodeURIComponent(REDIRECT)}`
     + `&terms_accepted_at=${encodeURIComponent(forged)}&terms_version=FORGED&activate=true`
-    + '&profile_state=active',
+    + '&profile_state=active&terms_accepted_source=grandfathered',
   );
   assert.equal(res.status, 302);
   const row = pool.accounts.get('4242');
   assert.equal(row.terms_accepted_at, NOW, 'a caller-supplied timestamp reached the acceptance record');
   assert.equal(row.terms_version, TERMS_VERSION, 'a caller-supplied version reached the acceptance record');
+  assert.equal(row.terms_accepted_source, 'signin', 'a caller-supplied source reached the acceptance record');
 
   // And structurally: the forged values are nowhere in the statement's params,
   // so there is no path by which a later refactor could start reading them.
@@ -403,6 +438,7 @@ await ta('the acceptance cannot be forged from the query string or the body', as
   const flat = JSON.stringify(upserts[0].params);
   assert.doesNotMatch(flat, /FORGED/, 'a caller-controlled value was bound into the acceptance statement');
   assert.doesNotMatch(flat, /1999/, 'a caller-controlled timestamp was bound into the acceptance statement');
+  assert.doesNotMatch(flat, /grandfathered/, 'a caller-controlled source was bound into the acceptance statement');
   assert.equal(upserts[0].params.length, 6,
     'the statement grew a parameter — every one of them must come from the hub session or a constant');
   assert.equal(upserts[0].params[5], TERMS_VERSION, 'the version parameter must be the server constant');
@@ -448,6 +484,7 @@ await ta('signing in twice does not rewrite or duplicate the acceptance', async
   assert.equal(row.terms_accepted_at, NOW,
     `the second sign-in restamped the acceptance (${row.terms_accepted_at}) — the record no longer says when consent was actually given`);
   assert.equal(row.terms_version, TERMS_VERSION);
+  assert.equal(row.terms_accepted_source, 'signin');
   assert.equal(pool.accounts.size, 1, 'a second row was created — one account, one acceptance');
 });
 
@@ -478,6 +515,63 @@ await ta('a federated check-in creates an account with NO acceptance at all', as
   assert.equal(row.profile_state, 'provisional');
 });
 
+// A grandfathered acceptance (platform_identity_024, task 1003360) was given on
+// the builder's behalf, not by them. It keeps the account published, but it is
+// not the first acceptance a HUMAN gave — so it must give way to one.
+const grandfathered = () => ({
+  github_id: '4242', github_login: 'octo', profile_state: 'active', handle: 'h',
+  account_visibility: 'public', hide_stats: false,
+  terms_accepted_at: GRANDFATHERED_AT, terms_version: '2026-08-29', terms_accepted_source: 'grandfathered',
+});
+
+await ta('a grandfathered acceptance gives way to the builder’s own at their next sign-in', async () => {
+  SESSION = HUB_SESSION;
+  pool.accounts.clear();
+  pool.accounts.set('4242', grandfathered());
+  pool.setClock(LATER);
+  await authorize();
+  const row = pool.accounts.get('4242');
+  assert.equal(row.terms_accepted_source, 'signin',
+    'the builder signed in and accepted, yet the record still says the acceptance was given on their behalf');
+  assert.equal(row.terms_accepted_at, LATER, 'the date must be when THEY accepted, not when the grandfather ran');
+  assert.equal(row.terms_version, TERMS_VERSION, 'and name the text served when they did');
+
+  // ...and from then on it is a sign-in like any other: written once.
+  pool.setClock('2026-09-01T00:00:00.000Z');
+  await authorize();
+  assert.equal(pool.accounts.get('4242').terms_accepted_at, LATER,
+    'a second sign-in restamped an acceptance the builder gave themselves');
+});
+
+await ta('an acceptance with no source on record is a real sign-in: it keeps its date and is marked signin', async () => {
+  // The deploy window: migrate.sh commits 024 while the old server still runs, and
+  // a builder signing in then gets an acceptance the old code wrote without a
+  // source. Treating "not signin" as "replace me" would erase the date they gave.
+  SESSION = HUB_SESSION;
+  pool.accounts.clear();
+  pool.accounts.set('4242', { ...grandfathered(), terms_accepted_at: NOW, terms_version: TERMS_VERSION, terms_accepted_source: null });
+  pool.setClock(LATER);
+  await authorize();
+  const row = pool.accounts.get('4242');
+  assert.equal(row.terms_accepted_at, NOW, 'a sign-in restamped an acceptance a human gave, because its source was blank');
+  assert.equal(row.terms_accepted_source, 'signin', 'and the source should now say how it was given');
+});
+
+await ta('a write that is not the capture point leaves a grandfathered acceptance marked grandfathered', async () => {
+  pool.accounts.clear();
+  pool.accounts.set('4242', grandfathered());
+  pool.setClock(LATER);
+  const pi = require('../modules/platform-identity/platform-identity.js');
+  // The non-activating upsert (the /me/handle and device-poll paths) and the
+  // federated check-in. Neither witnessed an acceptance, so neither may turn a
+  // grandfather into a sign-in — that would be the fiction the mark prevents.
+  await pi.upsertAccount({ githubId: '4242', githubLogin: 'octo', displayName: 'x', avatarUrl: null }, { pool });
+  await pi.ensureAccount({ githubId: '4242', githubLogin: 'octo', displayName: 'x', avatarUrl: null }, { pool });
+  const row = pool.accounts.get('4242');
+  assert.equal(row.terms_accepted_source, 'grandfathered', 'a write that witnessed no acceptance relabelled a grandfather as a sign-in');
+  assert.equal(row.terms_accepted_at, GRANDFATHERED_AT);
+});
+
 server.close();
 
 // ===========================================================================
@@ -503,12 +597,168 @@ t('the shared consent predicate requires the acceptance, in both forms', () => {
   assert.match(accountActiveSql('pa'), /pa\.terms_accepted_at IS NOT NULL/, 'and qualify it under an alias');
 });
 
+t('a grandfathered account is consented and published — nothing goes dark (owner decision, blocker 1000123)', () => {
+  // The predicate asks whether an acceptance exists, never how it was given: the
+  // source is for the ledger, not a second visibility rule (ADR 0202 D4).
+  const row = { profile_state: 'active', terms_accepted_at: GRANDFATHERED_AT, terms_accepted_source: 'grandfathered', account_visibility: 'public' };
+  assert.equal(isAccountActive(row), true, 'a grandfathered account went dark — the outcome the owner chose against');
+  assert.equal(isAccountVisible(row), true);
+  assert.doesNotMatch(accountActiveSql(), /terms_accepted_source/,
+    'the consent predicate started reading the source — a grandfather would stop publishing, or a second rule was born');
+});
+
 t('the page and the code agree on which version is current', () => {
   assert.match(termsHtml, new RegExp(TERMS_VERSION.replace(/-/g, '\\-')),
     `the page must state the version the code stamps (${TERMS_VERSION}) — a record naming a text the reader `
     + 'cannot find is not evidence of anything');
 });
 
+// ===========================================================================
+// 5b. The grandfather (platform_identity_024) — one-shot, marked, and narrow
+// ===========================================================================
+
+// The owner chose to grandfather existing accounts (blocker 1000123) and to MARK
+// them as grandfathered. Static checks on the migration's own text pin that it
+// is shaped that way; tests/terms_grandfather_db.mjs executes it against a real
+// Postgres in the integration lane.
+
+console.log('\nthe grandfather (existing accounts, marked as such):');
+
+const MIGRATION = 'platform_identity_024_terms_grandfathered.sql';
+const migrationSrc = fs.readFileSync(path.join(repo, 'modules', 'platform-identity', 'migrations', MIGRATION), 'utf8');
+const migrationSql = migrationSrc.replace(/--[^\n]*/g, '').replace(/\s+/g, ' ');
+
+t('the migration adds a source column that can only say signin or grandfathered', () => {
+  assert.match(migrationSql, /ADD COLUMN terms_accepted_source text CHECK \(terms_accepted_source IN \('signin', 'grandfathered'\)\)/,
+    'the source must be constrained — a free-text marker is one typo away from a third, meaningless kind of acceptance');
+});
+
+t('existing sign-in acceptances are marked as sign-ins BEFORE anything is grandfathered', () => {
+  const signin = migrationSql.indexOf("SET terms_accepted_source = 'signin' WHERE terms_accepted_at IS NOT NULL");
+  const grandfather = migrationSql.indexOf("terms_accepted_source = 'grandfathered'");
+  assert.notEqual(signin, -1, 'acceptances written by a real sign-in before this migration must be marked signin');
+  assert.notEqual(grandfather, -1, 'the grandfather write is missing');
+  assert.ok(signin < grandfather,
+    'the signin backfill must run first — after the grandfather it would relabel every grandfathered row as a sign-in');
+});
+
+t('only accounts the hub already witnessed are grandfathered, and nobody is activated by it', () => {
+  // The version is the text in force when the grandfather ran. It is pinned, not
+  // read from TERMS_VERSION: a later revision must not rewrite what these rows were accepted under.
+  assert.match(migrationSql,
+    /SET terms_accepted_at = now\(\), terms_version = '2026-08-29', terms_accepted_source = 'grandfathered' WHERE profile_state = 'active' AND terms_accepted_at IS NULL;/,
+    'the grandfather must stamp all three columns, and only on active accounts with no acceptance yet');
+  assert.equal((migrationSql.match(/profile_state/g) || []).length, 1,
+    'the migration names profile_state outside its one WHERE — it must never activate an account (a provisional account was never public)');
+});
+
+t('the grandfather runs once — replaying the migration cannot grandfather an account created since', () => {
+  const guard = migrationSql.search(/IF NOT EXISTS \( SELECT 1 FROM information_schema\.columns WHERE table_schema = current_schema\(\) AND table_name = 'platform_identity_accounts' AND column_name = 'terms_accepted_source' \) THEN/);
+  const endIf = migrationSql.indexOf('END IF;');
+  assert.notEqual(guard, -1, 'the data writes must be guarded on the column not existing yet');
+  for (const write of ['ADD COLUMN terms_accepted_source', "terms_accepted_source = 'signin'", "terms_accepted_source = 'grandfathered'"]) {
+    const at = migrationSql.indexOf(write);
+    assert.ok(at > guard && at < endIf, `${write} sits outside the one-shot guard`);
+  }
+});
+
+// ===========================================================================
+// 5c. The write-site guard — one writer, and no runtime grandfather
+// ===========================================================================
+
+// tests/effective_visibility_predicate.mjs deliberately does NOT match a write
+// (it proves so), so it cannot stop a second write site. This does: only
+// terms-acceptance.js may spell a write of the acceptance columns, and no server
+// code at all may write the grandfather marker — the migration is its only author.
+
+console.log('\nthe write-site guard (one writer, no runtime grandfather):');
+
+// Drop // and /* */ comments, keeping string and template-literal contents.
+function stripComments(src) {
+  let out = '';
+  let i = 0;
+  let quote = null;
+  while (i < src.length) {
+    const c = src[i];
+    const n = src[i + 1];
+    if (quote) {
+      out += c;
+      if (c === '\\') { out += n || ''; i += 2; continue; }
+      if (c === quote) quote = null;
+      i++;
+      continue;
+    }
+    if (c === '/' && n === '/') { while (i < src.length && src[i] !== '\n') i++; continue; }
+    if (c === '/' && n === '*') { const end = src.indexOf('*/', i + 2); i = end === -1 ? src.length : end + 2; continue; }
+    if (c === "'" || c === '"' || c === '`') quote = c;
+    out += c;
+    i++;
+  }
+  return out;
+}
+
+const ACCEPTANCE_WRITE = [
+  /\bterms_(?:accepted_at|version|accepted_source)\s*=(?!=)/g,
+  /INSERT\s+INTO\s+platform_identity_accounts\s*\([^)]*\bterms_(?:accepted_at|version|accepted_source)\b/gi,
+];
+const GRANDFATHER_LITERAL = /(['"`])grandfathered\1/;
+const acceptanceWritesIn = (code) => ACCEPTANCE_WRITE.flatMap((re) => [...code.matchAll(re)].map((m) => m[0]));
+
+function serverSources() {
+  const out = [];
+  const walk = (dir) => {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      const p = path.join(dir, e.name);
+      if (e.isDirectory()) { if (!['node_modules', 'public', 'tests', 'migrations'].includes(e.name)) walk(p); }
+      else if (e.name.endsWith('.js')) out.push(p);
+    }
+  };
+  walk(path.join(repo, 'src'));
+  walk(path.join(repo, 'modules'));
+  return out.map((abs) => ({ rel: path.relative(repo, abs).split(path.sep).join('/'), code: stripComments(fs.readFileSync(abs, 'utf8')) }));
+}
+const SOURCES = serverSources();
+const WRITER = 'modules/platform-identity/terms-acceptance.js';
+
+t('the guard catches a write in every form, and leaves reads and comparisons alone', () => {
+  assert.ok(acceptanceWritesIn('UPDATE platform_identity_accounts SET terms_accepted_at = now()').length, 'an UPDATE SET');
+  assert.ok(acceptanceWritesIn("terms_accepted_source='signin'").length, 'an unspaced assignment');
+  assert.ok(acceptanceWritesIn('INSERT INTO platform_identity_accounts (github_id, terms_version) VALUES ($1, $2)').length, 'an INSERT column list');
+  assert.ok(!acceptanceWritesIn('account.terms_accepted_at != null').length, 'a JS null comparison is not a write');
+  assert.ok(!acceptanceWritesIn('row.terms_accepted_source === x').length, 'nor a strict comparison');
+  assert.ok(!acceptanceWritesIn('SELECT profile_state, terms_accepted_at FROM platform_identity_accounts').length, 'nor a projection');
+  assert.ok(!acceptanceWritesIn(stripComments('// SET terms_accepted_at = now()\nconst x = 1;')).length, 'nor a comment');
+  assert.ok(stripComments("const u = 'https://x.example/a'; // c").includes('https://x.example/a'), 'a // inside a string is not a comment');
+  assert.ok(GRANDFATHER_LITERAL.test("a = 'grandfathered'"), 'the grandfather literal');
+  assert.ok(!GRANDFATHER_LITERAL.test(stripComments('// marked grandfathered\nconst y = 2;')), 'but not the word in prose');
+});
+
+t('terms-acceptance.js is the only server file that writes an acceptance', () => {
+  const writer = SOURCES.find((s) => s.rel === WRITER);
+  assert.ok(writer && acceptanceWritesIn(writer.code).length >= 3,
+    'the one writer no longer spells its writes — this guard would now pass vacuously');
+  const others = SOURCES.filter((s) => s.rel !== WRITER && acceptanceWritesIn(s.code).length)
+    .map((s) => `${s.rel}: ${acceptanceWritesIn(s.code).join(' | ')}`);
+  assert.deepEqual(others, [],
+    'a second acceptance write site — it bypasses the source marker and the capture-point proof above');
+});
+
+t('no server code can mark an acceptance grandfathered — only the migration ever did', () => {
+  assert.ok(SOURCES.length > 50, `the walk found only ${SOURCES.length} files — it is not looking where the code is`);
+  const hits = SOURCES.filter((s) => s.rel !== WRITER && GRANDFATHER_LITERAL.test(s.code)).map((s) => s.rel);
+  assert.deepEqual(hits, [],
+    'server code names the grandfather marker — a runtime grandfather records a consent nobody gave');
+  // The writer may READ the marker (a grandfather is the one acceptance a sign-in
+  // replaces) and nothing else: every mention is a test of the OLD row's source.
+  // Writing it is also refused behaviourally — the interpreter above knows no
+  // 'grandfathered' source expression, so a SET or VALUES producing it throws.
+  const writer = SOURCES.find((s) => s.rel === WRITER).code;
+  const mentions = (writer.match(/'grandfathered'/g) || []).length;
+  const reads = (writer.match(/\$\{self\}\.terms_accepted_source = 'grandfathered'/g) || []).length;
+  assert.ok(mentions >= 1 && mentions === reads,
+    `terms-acceptance.js names the grandfather marker ${mentions} time(s), only ${reads} as a read of the old row`);
+});
+
 // ===========================================================================
 // 6. The projection rule — a twin cannot judge a column it was not given
 // ===========================================================================

package/tests/terms_grandfather_db.mjs

@@ -0,0 +1,144 @@
+// tests/terms_grandfather_db.mjs — task 1003360 (owner decision on blocker
+// 1000123; ADR 0217 D3, amending ADR 0213 D4). Real DB.
+//
+// Proves migration platform_identity_024 against real SQL: an account the hub
+// had already witnessed is published immediately after the migration, without
+// signing in again; its acceptance is queryably distinct from a real sign-in;
+// the grandfather runs once; and the owner's next hub sign-in replaces it.
+// tests/terms_acceptance.mjs pins the same rules DB-free (the statement shapes
+// and the executed conflict branch); only a transaction engine can run the
+// migration's DO block and its UPDATEs.
+//
+// It builds its own tables in a throwaway schema, so it cannot see or disturb a
+// shared database's rows, and the migration's one-shot guard (keyed on the
+// column existing) starts from a genuinely fresh table every run.
+//
+// Real-DB integration test: self-skips without a reachable Postgres; in the
+// INTEGRATION set (scripts/gds/run-unit-tests.js) so the default DB-free lane
+// never runs it.
+//
+// Run:  DATABASE_URL=... node tests/terms_grandfather_db.mjs
+
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { strict as assert } from 'node:assert';
+const require = createRequire(import.meta.url);
+const { Pool } = require('pg');
+const pi = require('../modules/platform-identity/platform-identity.js');
+const { accountActiveSql } = require('../modules/platform-identity/account-visibility.js');
+const { TERMS_VERSION } = require('../modules/platform-identity/terms-acceptance.js');
+
+const here = dirname(fileURLToPath(import.meta.url));
+const MIG_DIR = join(here, '..', 'modules', 'platform-identity', 'migrations');
+const migrationSql = (f) => readFileSync(join(MIG_DIR, f), 'utf8');
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL || undefined, max: 1 });
+let client;
+try {
+  client = await pool.connect();
+} catch (e) {
+  console.log(`terms_grandfather_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+const SCHEMA = `t1003360_${process.pid}`;
+const LEGACY = 90336001, SIGNED = 90336002, PROV = 90336003, LATE = 90336004;
+const q = (sql, params) => client.query(sql, params);
+const row = async (id) => (await q(
+  'SELECT profile_state, terms_accepted_at, terms_version, terms_accepted_source FROM platform_identity_accounts WHERE github_id = $1', [id],
+)).rows[0];
+
+let pass = 0;
+const ok = (cond, msg) => { assert.ok(cond, msg); pass++; console.log(`  ok - ${msg}`); };
+
+try {
+  await q(`CREATE SCHEMA ${SCHEMA}`);
+  await q(`SET search_path TO ${SCHEMA}`);
+  // The columns upsertAccount writes and reads: 001 the table, 007 consent, 008
+  // the handle, 009 display_name_source, 019 the acceptance pair.
+  for (const f of ['001_tables', '007_profile_consent', '008_handle', '009_profile_fields', '019_terms_acceptance']) {
+    await q(migrationSql(`platform_identity_${f}.sql`));
+  }
+
+  // The world 024 lands on: a legacy account the hub witnessed before the terms
+  // existed, one that accepted by a real sign-in since, and one never witnessed.
+  await q(
+    `INSERT INTO platform_identity_accounts (github_id, github_login, handle, profile_state, terms_accepted_at, terms_version)
+     VALUES ($1, 'legacy-b', 'legacy-b', 'active', NULL, NULL),
+            ($2, 'signed-b', 'signed-b', 'active', '2026-09-01T10:00:00Z', '2026-08-29'),
+            ($3, 'prov-b',   'prov-b',   'provisional', NULL, NULL)`,
+    [LEGACY, SIGNED, PROV],
+  );
+  const published = async () => (await q(
+    `SELECT github_id::text FROM platform_identity_accounts WHERE ${accountActiveSql()} ORDER BY github_id`,
+  )).rows.map((r) => Number(r.github_id));
+  ok((await published()).join() === String(SIGNED), 'before 024: the legacy account is dark (ADR 0213 D4, the state the owner chose against)');
+
+  await q(migrationSql('platform_identity_024_terms_grandfathered.sql'));
+
+  // Done-when 1: visible immediately, without signing in again.
+  ok((await published()).join() === [LEGACY, SIGNED].join(), 'after 024: the legacy account is published again, and nobody else newly is');
+
+  // Done-when 2: queryably distinct from a real sign-in.
+  const legacy = await row(LEGACY);
+  ok(legacy.terms_accepted_source === 'grandfathered', 'the legacy acceptance is marked grandfathered');
+  ok(legacy.terms_version === '2026-08-29' && legacy.terms_accepted_at !== null, 'and names the text and moment it was recorded under');
+  const signed = await row(SIGNED);
+  ok(signed.terms_accepted_source === 'signin', 'an acceptance a real sign-in wrote is marked signin');
+  ok(signed.terms_accepted_at.toISOString() === '2026-09-01T10:00:00.000Z', 'and its date is left exactly as the builder gave it');
+  const prov = await row(PROV);
+  ok(prov.profile_state === 'provisional' && prov.terms_accepted_at === null && prov.terms_accepted_source === null,
+    'a never-witnessed account is neither activated nor grandfathered — it was never public');
+  const counts = (await q(
+    `SELECT terms_accepted_source AS s, count(*)::int AS n FROM platform_identity_accounts
+      WHERE terms_accepted_source IS NOT NULL GROUP BY 1 ORDER BY 1`,
+  )).rows.map((r) => `${r.s}:${r.n}`).join();
+  ok(counts === 'grandfathered:1,signin:1', `an audit can count the two kinds apart (${counts})`);
+
+  // One-shot: an account that turns up legacy-shaped later is not grandfathered by a replay.
+  await q(
+    `INSERT INTO platform_identity_accounts (github_id, github_login, handle, profile_state) VALUES ($1, 'late-b', 'late-b', 'active')`,
+    [LATE],
+  );
+  await q(migrationSql('platform_identity_024_terms_grandfathered.sql'));
+  ok((await row(LATE)).terms_accepted_at === null, 'replaying 024 grandfathers nobody new — the grandfather was an event, not a rule');
+
+  // The owner's next hub sign-in replaces the grandfather with their own acceptance.
+  await pi.upsertAccount({ githubId: LEGACY, githubLogin: 'legacy-b', activate: true }, { pool: client });
+  const after = await row(LEGACY);
+  ok(after.terms_accepted_source === 'signin', 'the next sign-in replaces the grandfather with a signin');
+  ok(after.terms_accepted_at > legacy.terms_accepted_at && after.terms_version === TERMS_VERSION,
+    'dated when they signed in, under the text served then');
+  await pi.upsertAccount({ githubId: LEGACY, githubLogin: 'legacy-b', activate: true }, { pool: client });
+  ok((await row(LEGACY)).terms_accepted_at.getTime() === after.terms_accepted_at.getTime(), 'and a second sign-in does not restamp it');
+
+  await pi.upsertAccount({ githubId: SIGNED, githubLogin: 'signed-b', activate: true }, { pool: client });
+  ok((await row(SIGNED)).terms_accepted_at.toISOString() === '2026-09-01T10:00:00.000Z', 'an existing signin is never restamped either');
+
+  await pi.upsertAccount({ githubId: PROV, githubLogin: 'prov-b' }, { pool: client });
+  ok((await row(PROV)).terms_accepted_source === null, 'a non-activating upsert records no acceptance');
+
+  // The deploy window: 024 has committed but the old server wrote this sign-in,
+  // with no source. It is a real acceptance, so the next sign-in keeps its date.
+  await q(`UPDATE platform_identity_accounts SET terms_accepted_at = '2026-09-02T08:00:00Z', terms_version = '2026-08-29' WHERE github_id = $1`, [LATE]);
+  await pi.upsertAccount({ githubId: LATE, githubLogin: 'late-b', activate: true }, { pool: client });
+  const late = await row(LATE);
+  ok(late.terms_accepted_at.toISOString() === '2026-09-02T08:00:00.000Z' && late.terms_accepted_source === 'signin',
+    'an acceptance written without a source keeps its date and is marked signin');
+
+  // Last, and unparameterised: nothing after an erroring statement depends on how the session recovers.
+  await assert.rejects(
+    q(`UPDATE platform_identity_accounts SET terms_accepted_source = 'implied' WHERE github_id = ${LEGACY}`),
+    /check constraint/i,
+  );
+  ok(true, 'the source column refuses a third kind of acceptance');
+
+  console.log(`\nterms_grandfather_db.mjs: ${pass} passed`);
+} finally {
+  await q(`DROP SCHEMA IF EXISTS ${SCHEMA} CASCADE`).catch(() => {});
+  client.release();
+  await pool.end().catch(() => {});
+}