Truthful provenance for an operator-invoked snapshot

The internal one-shot route already called the SAME production runSnapshot with
the SAME default dependencies — but it passed no trigger, and runSnapshot
defaults an absent trigger to SCHEDULED. So every operator-invoked run was
recorded as though the cron had fired it. That was a lie about provenance,
present by omission, and it would have contaminated the trace of any forced
diagnostic run.

CONTROLLED_FORCED is now its own trigger. Both internal routes (`/snapshot/:sport`
and `/snapshot/all`) stamp it, along with the process generation. The scheduler
still stamps SCHEDULED, and a test asserts neither internal route can label
itself scheduled.

Trace retention moves from "scheduled only" to a named allow-list of SCHEDULED +
CONTROLLED_FORCED. INTRADAY is still refused — it runs every ~20 minutes and
would displace scheduled evidence, which is the failure the store exists to
prevent. MANUAL_API stays refused too.

THE PIPELINE IS UNTOUCHED. snapshotService, gradeSlateService, retentionService,
snapshotScheduler, oddsService and eventIdentity are all UNCHANGED. A test
asserts the route injects no dependency override — no getOdds, gradeAndCacheSlate,
retention, ledger, cacheSet/cacheGet, gameBinder, eventIdentity, mlbAdapter or
notify — so the only difference from a scheduled invocation is the label and the
absence of a scheduled hour, which a forced run genuinely does not have.

The ?limit bisect-hook invariant is preserved and tightened: the opts passed
carry exactly {trigger, processStartedAt} and never a stray limit.

Teeth, injections verified present, against a green baseline:
  :sport route mislabelled SCHEDULED -> 3 fail
  /all route mislabelled SCHEDULED   -> 2 fail
  intraday admitted to the store     -> 5 fail
  trigger filter removed             -> 3 fail

THE FIRST TEETH RUN WAS INVALID AND IS DISCARDED: both routes live in one file,
so a single-occurrence replace hit `/snapshot/all` and left `/snapshot/:sport`
correct — the injection landed on the wrong target and the suite passed. Coverage
for `/all` was added, plus a test that the file contains exactly two
CONTROLLED_FORCED stamps and zero SCHEDULED ones, then both were re-run failing
independently.

Four stale assertions updated with the reason recorded: three pinned the
`not_scheduled` refusal string (now trigger-agnostic) and one pinned an empty
opts object on the route.

389 suites / 5,280 tests pass. web tsc exit 0. Lineage stays OFF.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CQJeAG8vcDoL5zkiaJyVb8

src/routes/internal.js

@@ -180,7 +180,11 @@ router.post('/prefetch/tank01', async (req, res) => {
 router.post('/snapshot/all', async (req, res) => {
   const snapshot = require('../services/snapshotService');
   try {
-    const results = await snapshot.runAllSnapshots();
+    const acqT = require('../services/ops/acquisitionTrace');
+    const results = await snapshot.runAllSnapshots({
+      trigger: acqT.TRIGGER.CONTROLLED_FORCED,
+      processStartedAt: PROCESS_STARTED_AT,
+    });
     return res.json({ ok: true, results });
   } catch (err) {
     const message = err && err.message ? err.message : String(err);
@@ -283,7 +287,17 @@ router.post('/snapshot/:sport', async (req, res) => {
     // slate for one run so a cap regression can be isolated by measurement
     // rather than guessed at. Omitted => gradeSlateService's real DEFAULT_LIMIT.
     const limit = Number(req.query.limit) > 0 ? Number(req.query.limit) : undefined;
-    const summary = await snapshot.runSnapshot(req.params.sport, limit ? { limit } : {});
+    // TRUTHFUL PROVENANCE. runSnapshot defaults an absent trigger to SCHEDULED,
+    // so an operator-invoked run was previously recorded as though the cron
+    // fired it. It is now labelled for what it is. This changes ONLY the
+    // diagnostic trace — the pipeline path, the dependencies and every
+    // authoritative write are identical to the scheduled invocation.
+    const acqT = require('../services/ops/acquisitionTrace');
+    const summary = await snapshot.runSnapshot(req.params.sport, {
+      ...(limit ? { limit } : {}),
+      trigger: acqT.TRIGGER.CONTROLLED_FORCED,
+      processStartedAt: PROCESS_STARTED_AT,
+    });
     return res.json({ ok: true, ...(limit ? { limit_override: limit } : {}), summary });
   } catch (err) {
     const message = err && err.message ? err.message : String(err);

src/services/ops/acquisitionTrace.js

@@ -39,10 +39,23 @@ const TTL_SECONDS = 172800; // 48h
 
 const TRIGGER = Object.freeze({
   SCHEDULED: 'SCHEDULED_SNAPSHOT',
+  // An operator-invoked run of the SAME production snapshot path. Recorded
+  // under its own name because labelling it SCHEDULED would be a lie about
+  // provenance — and the internal route previously did exactly that by
+  // omission, since `deps.trigger || TRIGGER.SCHEDULED` defaults that way.
+  CONTROLLED_FORCED: 'CONTROLLED_FORCED',
   INTRADAY: 'INTRADAY_REFRESH',
   MANUAL: 'MANUAL_API',
 });
 
+/**
+ * Which triggers are retained. A controlled forced run is a legitimate one-shot
+ * diagnostic of the production path and is kept, tagged as itself. INTRADAY is
+ * still refused: it runs every ~20 minutes and would displace scheduled
+ * evidence, which is the failure this store exists to prevent.
+ */
+const RETAINED_TRIGGERS = Object.freeze([TRIGGER.SCHEDULED, TRIGGER.CONTROLLED_FORCED]);
+
 const SOURCE_OUTCOME = Object.freeze({
   NONZERO: 'NONZERO',
   ZERO: 'ZERO',
@@ -202,7 +215,7 @@ async function persist(trace, deps = {}) {
   if (!trace || !trace.sport) return { stored: false, reason: 'no_sport' };
   // Only SCHEDULED attempts are retained; an intraday success must not be able
   // to displace a scheduled failure.
-  if (trace.trigger !== TRIGGER.SCHEDULED) return { stored: false, reason: 'not_scheduled' };
+  if (!RETAINED_TRIGGERS.includes(trace.trigger)) return { stored: false, reason: 'not_retained_trigger' };
   return pushBounded(key(trace.sport), trace, deps);
 }
 
@@ -389,7 +402,7 @@ function finishPregrade(trace, { now } = {}) {
 
 async function persistPregrade(trace, deps = {}) {
   if (!trace || !trace.sport) return { stored: false, reason: 'no_sport' };
-  if (trace.trigger !== TRIGGER.SCHEDULED) return { stored: false, reason: 'not_scheduled' };
+  if (!RETAINED_TRIGGERS.includes(trace.trigger)) return { stored: false, reason: 'not_retained_trigger' };
   return pushBounded(pregradeKey(trace.sport), trace, deps);
 }
 
@@ -399,7 +412,7 @@ async function pregradeHistory(sport, deps = {}) {
 
 
 module.exports = {
-  TRIGGER, SOURCE_OUTCOME, FINAL, OUTCOME, PREGRADE_OUTCOME,
+  TRIGGER, RETAINED_TRIGGERS, SOURCE_OUTCOME, FINAL, OUTCOME, PREGRADE_OUTCOME,
   pregradeKey, beginPregrade, pregradeRecorder, classifyPregrade, finishPregrade,
   reconcilePregrade,
   persistPregrade, pregradeHistory,