forge: config.sparseMarks — re-target the trailing mark instead of stacking

Anchoring "one super-commit per period" clashed with a fast commit cadence:
recordTip appends a pending mark per commit, so marking HEAD walked one tx per
commit. With config.sparseMarks, when the trailing mark is still unfunded a new
tip RE-TARGETS it (re-derives program/address over the same marked prefix)
rather than stacking. The chain gains a link only per funded mark, so anchoring
HEAD is a single tx however many commits landed — fresh mirrors (frequent
commits) now coexist with cheap, sparse anchoring. Default off; explicit
opt-in, existing behavior and every other test unchanged.

Tests: +1 (127) — two post-genesis pushes re-target ONE pending mark (count
holds at 2, address moves to the new tip), genesis stays marked.

Author: melvincarvalho

forge/AGENT.md

@@ -134,6 +134,12 @@ Key properties:
   and persisted in `pluginDir`).
 - `chain` — Blocktrails chain (default a testnet); mainnet requires
   `allowMainnet: true`.
+- `sparseMarks` — when true, a new tip RE-TARGETS the trailing unfunded mark
+  instead of stacking one pending mark per commit. The chain then gains a link
+  only per *funded* mark, so anchoring HEAD is one tx per period regardless of
+  commit cadence — the "rolling mark" that lets fast commits (fresh mirrors)
+  coexist with slow, cheap anchoring. Default off (each commit is its own
+  candidate state).
 - `cspConnect: [origin, …]` — extra `connect-src` origins for a login widget
   that talks to external identity providers.
 - `pushTokenTtl`, `gitHttpBackend` — see `README.md`.

forge/plugin.js

@@ -885,6 +885,13 @@ export async function activate(api) {
       + '(no owner signature required). DEMO ONLY; never enable on a real forge.');
   }
 
+  // Sparse marking (opt-in): instead of stacking one pending mark per commit,
+  // RE-TARGET the trailing UNFUNDED mark at each new tip — so the chain gains a
+  // link only per actual (funded) mark and anchoring HEAD is ONE tx regardless
+  // of how many commits landed since. Lets a fast commit cadence (fresh mirrors)
+  // coexist with a slow mark cadence (one super-commit per period). See recordTip.
+  const sparseMarks = api.config.sparseMarks === true;
+
   // Tier 3.5: anchoring chain, testnet4 by default. Checked FIRST, before
   // any other activation work. Mainnet is REFUSED at
   // activate unless the operator opts in explicitly — this plugin derives
@@ -1510,6 +1517,24 @@ export async function activate(api) {
       if (!trail) return;
       const last = trail.marks.at(-1);
       if (last && last.state.commit === tip && last.state.branch === branch) return; // tip unchanged
+      if (sparseMarks && last && last.status === 'pending') {
+        // sparse: the trailing mark is unfunded, so RE-TARGET it at the new tip
+        // (re-derive its program/address chaining the same MARKED prefix) rather
+        // than stacking. The chain gains a link only when a mark is actually
+        // funded, so anchoring HEAD stays one tx however many commits landed.
+        const state = { commit: tip, repo: `${owner}/${name}`, branch };
+        const stateHash = markStateHash(state);
+        const hashes = [...trail.marks.slice(0, -1).map((m) => m.stateHash), stateHash];
+        const program = trailProgram(trail.pubkeyBase, hashes);
+        last.state = state;
+        last.stateHash = stateHash;
+        last.program = program;
+        last.address = p2trAddressEncode(chainHrp, Buffer.from(program, 'hex'));
+        last.at = Math.floor(Date.now() / 1000);
+        saveTrail(owner, name, trail);
+        api.log.info(`forge: mark #${last.index} re-targeted (sparse) for ${owner}/${name}@${branch} (${tip.slice(0, 7)}) -> ${last.address}`);
+        return;
+      }
       if (trail.marks.length >= MARKS_CAP) {
         api.log.warn(`forge: ${owner}/${name} hit the ${MARKS_CAP}-mark cap — not recording ${tip.slice(0, 7)}`);
         return;

forge/test.js

@@ -2422,6 +2422,57 @@ describe('forge plugin', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Sparse marking (config.sparseMarks): the trailing UNFUNDED mark is re-targeted
+// at each new tip instead of stacked, so anchoring HEAD is one tx per period.
+describe('forge sparse marking (config.sparseMarks re-targets, does not stack)', () => {
+  let jss; let base; let owner; let wdir;
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'forge-sparse-'));
+  const g = (args, opts = {}) => git(args, { ...opts, env: { HOME: tmp, ...(opts.env ?? {}) } });
+  const authed = () => ({ 'content-type': 'application/json', authorization: `Bearer ${owner.access_token}` });
+  const marksApi = () => `${base}/forge/api/repos/sparsey/r/marks`;
+  const marksOf = async () => (await fetch(marksApi())).json();
+  const until = async (fn, what, ms = 5000) => {
+    const t0 = Date.now();
+    for (;;) { const v = await fn(); if (v) return v; if (Date.now() - t0 > ms) throw new Error(`timed out: ${what}`); await new Promise((r) => { setTimeout(r, 50); }); }
+  };
+  const pushChange = async (content, msg) => {
+    fs.writeFileSync(path.join(wdir, 'a.txt'), content);
+    await g(['commit', '-aqm', msg], { cwd: wdir });
+    await g([...authFlag(owner.access_token), 'push', `${base}/forge/sparsey/r.git`, 'main'], { cwd: wdir });
+    return (await g(['rev-parse', 'HEAD'], { cwd: wdir })).stdout.trim();
+  };
+
+  before(async () => {
+    fs.writeFileSync(path.join(tmp, '.gitconfig'), '[user]\n\temail = s@e.org\n\tname = S\n[init]\n\tdefaultBranch = main\n');
+    jss = await startJss({ idp: true, plugins: [{ id: 'forge', module: module_, prefix: '/forge', config: { sparseMarks: true } }] });
+    base = jss.base;
+    owner = await registerAndMint(base, 'sparsey');
+    wdir = path.join(tmp, 'r'); fs.mkdirSync(wdir, { recursive: true });
+    fs.writeFileSync(path.join(wdir, 'a.txt'), '1\n');
+    await g(['init', '--quiet'], { cwd: wdir }); await g(['add', '-A'], { cwd: wdir }); await g(['commit', '--quiet', '-m', 'c1'], { cwd: wdir });
+    await g([...authFlag(owner.access_token), 'push', `${base}/forge/sparsey/r.git`, 'main'], { cwd: wdir });
+  });
+  after(async () => { if (jss) await jss.close(); fs.rmSync(tmp, { recursive: true, force: true }); });
+
+  it('after a funded genesis, repeated pushes re-target ONE pending mark (length stays 2)', async () => {
+    // enable + fund genesis so the mark to re-target is #1 (genesis #0 is marked)
+    assert.strictEqual((await fetch(`${marksApi()}/enable`, { method: 'POST', headers: authed(), body: '{}' })).status, 201);
+    await fetch(`${marksApi()}/0/txo`, { method: 'POST', headers: authed(), body: JSON.stringify({ txid: 'a'.repeat(64), vout: 0, amount: 100000 }) });
+    const c2 = await pushChange('2\n', 'c2');
+    let m = await until(async () => { const x = await marksOf(); return x.marks.length === 2 && x.marks[1].state.commit === c2 ? x : null; }, 'pending #1 for c2');
+    const addr1 = m.marks[1].address;
+    assert.strictEqual(m.marks[1].status, 'pending');
+
+    const c3 = await pushChange('3\n', 'c3');
+    m = await until(async () => { const x = await marksOf(); return x.marks[1].state.commit === c3 ? x : null; }, 'pending #1 re-targeted to c3');
+    assert.strictEqual(m.marks.length, 2, 'still genesis + ONE pending — re-targeted, not stacked');
+    assert.notStrictEqual(m.marks[1].address, addr1, 'the pending mark address moved to match the new tip');
+    assert.strictEqual(m.marks[1].status, 'pending');
+    assert.strictEqual(m.marks[0].status, 'marked', 'the funded genesis is untouched');
+  });
+});
+
 // ---------------------------------------------------------------------------
 // NIP-34 emission against a LIVE relay — an in-process ws relay that accepts
 // one EVENT and replies OK. Its own JSS instance (config.announceRelays set)