@dzhechkov/harness-core 0.8.5 → 0.8.10

package/src/guard-promotion.ts

@@ -38,6 +38,21 @@ export type RuleTemplate = 'pairing-check' | 'absence-check' | 'format-match';
 
 export const TEMPLATES: readonly RuleTemplate[] = ['pairing-check', 'absence-check', 'format-match'];
 
+export function isOffsetIsoTimestamp(value: unknown): value is string {
+  if (typeof value !== 'string') return false;
+  const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(Z|[+-](\d{2}):(\d{2}))$/.exec(value);
+  if (match === null || !Number.isFinite(Date.parse(value))) return false;
+  const [, yearText, monthText, dayText, hourText, minuteText, secondText, zone, offsetHourText, offsetMinuteText] = match;
+  const year = Number(yearText);
+  const month = Number(monthText);
+  const day = Number(dayText);
+  const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+  const daysInMonth = [0, 31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month] ?? 0;
+  return day >= 1 && day <= daysInMonth &&
+    Number(hourText) <= 23 && Number(minuteText) <= 59 && Number(secondText) <= 59 &&
+    (zone === 'Z' || (Number(offsetHourText) <= 23 && Number(offsetMinuteText) <= 59));
+}
+
 export interface TemplateParams {
   /** pairing-check: the glob whose presence in a change ARMS the rule. */
   readonly when?: string;
@@ -384,6 +399,23 @@ export function paramsKey(template: RuleTemplate, params: TemplateParams): strin
   return `${template}|${parts.join('&')}`;
 }
 
+/**
+ * Exact-byte discriminator of effective promoted-rule content. The ordered tuple keeps boundaries
+ * unambiguous; only its two-part digest is persisted, so lesson-derived literals are not copied into
+ * observational history. This is correlation identity, not authentication of a locally editable log.
+ */
+export function lessonRuleContentAnchor(template: RuleTemplate, params: TemplateParams): string {
+  const ordered = Object.keys(params ?? {})
+    .sort()
+    .map((key) => [key, String((params as Record<string, unknown>)[key])] as const);
+  const canonical = JSON.stringify([template, ordered]);
+  return `lesson-rule/v1:${fnv1a32(canonical)}${fnv1a32(`\u0000${canonical}`)}`;
+}
+
+export function isLessonRuleContentAnchor(value: unknown): value is string {
+  return typeof value === 'string' && /^lesson-rule\/v1:[a-f0-9]{16}$/.test(value);
+}
+
 /** A rule already present in the engine or the config, in the shape the dedup check consumes. */
 export interface ExistingRuleView {
   readonly id: string;
@@ -531,6 +563,8 @@ export interface LessonInput {
 export interface PromotionCandidate {
   readonly lessonId: string;
   readonly lessonText: string;
+  /** False only for quarantined hypotheses; classification alone never makes them eligible. */
+  readonly eligible: boolean;
   readonly ruleId: string | null;
   readonly template: RuleTemplate | null;
   readonly params: TemplateParams | null;
@@ -645,7 +679,7 @@ export function assembleCandidates(facts: PromotionFacts): PromotionReport {
     if (!l || typeof l.dzId !== 'string') continue;
     const uses = Number.isFinite(l.uses) && l.uses >= 0 ? Math.floor(l.uses) : 0;
     const cost = 1 + uses;
-    const base = { lessonId: l.dzId, lessonText: typeof l.text === 'string' ? l.text : '', cost, ruleId: null, template: null, params: null, score: 0, firings: 0, wins: 0, evaluatedPeriods: 0, periods: [], proposedRule: null, firstSeenTs: null, elapsedMs: 0, elapsedRequiredMs } as const;
+    const base = { lessonId: l.dzId, lessonText: typeof l.text === 'string' ? l.text : '', eligible: l.quarantined !== true, cost, ruleId: null, template: null, params: null, score: 0, firings: 0, wins: 0, evaluatedPeriods: 0, periods: [], proposedRule: null, firstSeenTs: null, elapsedMs: 0, elapsedRequiredMs } as const;
 
     if (l.quarantined === true) quarantinedSkipped += 1;
 
@@ -737,6 +771,31 @@ export function assembleCandidates(facts: PromotionFacts): PromotionReport {
 
 // ── State (ADR-004) ─────────────────────────────────────────────────────────────────────────────
 
+/** Enough prospective observations for multi-year monthly reporting without an unbounded journal. */
+export const MAX_PROMOTION_RUN_EVIDENCE = 120;
+/** A larger run is recorded as incomplete, so truncation becomes NOT MEASURED rather than a low count. */
+export const MAX_PROMOTION_RUN_CANDIDATES = 10_000;
+export const MAX_PROMOTION_ACCEPTANCE_EVIDENCE = 10_000;
+
+export interface PromotionRunCandidateEvidence {
+  readonly candidateAnchor: string;
+  readonly eligible: boolean;
+  readonly ruleContentAnchor: string | null;
+  readonly verdict: CandidateVerdict;
+}
+
+export interface PromotionRunEvidence {
+  readonly runId: string;
+  readonly ts: string;
+  readonly complete: boolean;
+  readonly candidates: readonly PromotionRunCandidateEvidence[];
+}
+
+export interface PromotionAcceptanceEvidence {
+  readonly ruleContentAnchor: string;
+  readonly acceptedTs: string;
+}
+
 export interface PromotionStateEntry {
   readonly ruleId: string;
   readonly lessonId: string;
@@ -759,10 +818,59 @@ export interface PromotionState {
   readonly version: 1;
   readonly nextAdrSeq: number;
   readonly entries: Readonly<Record<string, PromotionStateEntry>>;
+  /** Optional so a legacy v1 state remains distinguishable from a recorded zero-candidate run. */
+  readonly runs?: readonly PromotionRunEvidence[];
+  /** Months whose oldest whole run records were pruned; their promote counts are not measurable. */
+  readonly truncatedRunPeriods?: readonly string[];
+  /** Compact durable join provenance, independent of bounded per-run retention. */
+  readonly acceptances?: readonly PromotionAcceptanceEvidence[];
+  /** False means an unmatched promoted firing may belong to pre-feature or pruned provenance. */
+  readonly acceptanceHistoryComplete?: boolean;
 }
 
 export const EMPTY_PROMOTION_STATE: PromotionState = { version: 1, nextAdrSeq: 1, entries: {} };
 
+const CANDIDATE_VERDICTS: readonly CandidateVerdict[] = ['promote', 'wait', 'insufficient-data', 'duplicate', 'not-promotable'];
+
+function normalizePromotionRun(raw: unknown): PromotionRunEvidence | null {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const value = raw as Record<string, unknown>;
+  const runId = value['runId'];
+  const ts = value['ts'];
+  const candidates = value['candidates'];
+  if (typeof runId !== 'string' || runId === '' || runId.length > 512) return null;
+  if (!isOffsetIsoTimestamp(ts)) return null;
+  if (typeof value['complete'] !== 'boolean' || !Array.isArray(candidates)) return null;
+  if (candidates.length > MAX_PROMOTION_RUN_CANDIDATES) return null;
+  const normalized: PromotionRunCandidateEvidence[] = [];
+  for (const candidate of candidates) {
+    if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) return null;
+    const item = candidate as Record<string, unknown>;
+    const candidateAnchor = item['candidateAnchor'];
+    const ruleContentAnchor = item['ruleContentAnchor'];
+    const verdict = item['verdict'];
+    if (typeof candidateAnchor !== 'string' || candidateAnchor === '' || candidateAnchor.length > 512) return null;
+    if (typeof item['eligible'] !== 'boolean') return null;
+    if (ruleContentAnchor !== null && !isLessonRuleContentAnchor(ruleContentAnchor)) return null;
+    if (typeof verdict !== 'string' || !CANDIDATE_VERDICTS.includes(verdict as CandidateVerdict)) return null;
+    if (verdict === 'promote' && (item['eligible'] !== true || ruleContentAnchor === null)) return null;
+    normalized.push({
+      candidateAnchor,
+      eligible: item['eligible'],
+      ruleContentAnchor: ruleContentAnchor as string | null,
+      verdict: verdict as CandidateVerdict,
+    });
+  }
+  return { runId, ts, complete: value['complete'], candidates: normalized };
+}
+
+function normalizeAcceptance(raw: unknown): PromotionAcceptanceEvidence | null {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const value = raw as Record<string, unknown>;
+  if (!isLessonRuleContentAnchor(value['ruleContentAnchor']) || !isOffsetIsoTimestamp(value['acceptedTs'])) return null;
+  return { ruleContentAnchor: value['ruleContentAnchor'], acceptedTs: value['acceptedTs'] };
+}
+
 /**
  * Keys that must never become an entry name. `Object.hasOwn` stops a polluted JSON from being READ
  * through the prototype, but it does not stop `entries[key] = …` from WRITING through it: `JSON.parse`
@@ -784,6 +892,50 @@ export function normalizePromotionState(raw: unknown): PromotionState {
   const seqRaw = o['nextAdrSeq'];
   const nextAdrSeq = typeof seqRaw === 'number' && Number.isInteger(seqRaw) && seqRaw >= 1 && seqRaw <= 100_000 ? seqRaw : 1;
   const entries: Record<string, PromotionStateEntry> = {};
+  let runs: PromotionRunEvidence[] | undefined;
+  if (Object.hasOwn(o, 'runs')) {
+    runs = [];
+    if (Array.isArray(o['runs'])) {
+      const seen = new Set<string>();
+      for (const rawRun of o['runs']) {
+        const run = normalizePromotionRun(rawRun);
+        if (run === null || seen.has(run.runId)) continue;
+        seen.add(run.runId);
+        runs.push(run);
+      }
+      runs.sort((a, b) => Date.parse(a.ts) - Date.parse(b.ts) || a.runId.localeCompare(b.runId));
+      if (runs.length > MAX_PROMOTION_RUN_EVIDENCE) runs = runs.slice(-MAX_PROMOTION_RUN_EVIDENCE);
+    }
+  }
+  let truncatedRunPeriods: string[] | undefined;
+  if (Object.hasOwn(o, 'truncatedRunPeriods')) {
+    truncatedRunPeriods = Array.isArray(o['truncatedRunPeriods'])
+      ? [...new Set(o['truncatedRunPeriods'].filter((period): period is string =>
+        typeof period === 'string' && /^\d{4}-(?:0[1-9]|1[0-2])$/.test(period),
+      ))].sort().slice(-12)
+      : [];
+  }
+  let acceptances: PromotionAcceptanceEvidence[] | undefined;
+  if (Object.hasOwn(o, 'acceptances')) {
+    acceptances = [];
+    if (Array.isArray(o['acceptances'])) {
+      const byAnchor = new Map<string, PromotionAcceptanceEvidence>();
+      for (const rawAcceptance of o['acceptances']) {
+        const acceptance = normalizeAcceptance(rawAcceptance);
+        if (acceptance === null) continue;
+        const prior = byAnchor.get(acceptance.ruleContentAnchor);
+        if (prior === undefined || Date.parse(acceptance.acceptedTs) < Date.parse(prior.acceptedTs)) {
+          byAnchor.set(acceptance.ruleContentAnchor, acceptance);
+        }
+      }
+      acceptances = [...byAnchor.values()]
+        .sort((a, b) => Date.parse(a.acceptedTs) - Date.parse(b.acceptedTs) || a.ruleContentAnchor.localeCompare(b.ruleContentAnchor))
+        .slice(-MAX_PROMOTION_ACCEPTANCE_EVIDENCE);
+    }
+  }
+  const acceptanceHistoryComplete = typeof o['acceptanceHistoryComplete'] === 'boolean'
+    ? o['acceptanceHistoryComplete']
+    : undefined;
   const rawEntries = o['entries'];
   if (rawEntries && typeof rawEntries === 'object' && !Array.isArray(rawEntries)) {
     for (const key of Object.keys(rawEntries as Record<string, unknown>)) {
@@ -810,13 +962,21 @@ export function normalizePromotionState(raw: unknown): PromotionState {
         lastRunTs: str('lastRunTs') ?? '',
         wins: int('wins'),
         evaluatedPeriods: int('evaluatedPeriods'),
-        verdict: (['promote', 'wait', 'insufficient-data', 'duplicate', 'not-promotable'] as const).includes(str('verdict') as CandidateVerdict) ? (str('verdict') as CandidateVerdict) : 'wait',
+        verdict: CANDIDATE_VERDICTS.includes(str('verdict') as CandidateVerdict) ? (str('verdict') as CandidateVerdict) : 'wait',
         ...(adrSeq !== undefined ? { adrSeq } : {}),
         ...(str('appliedTs') !== undefined ? { appliedTs: str('appliedTs')! } : {}),
       };
     }
   }
-  return { version: 1, nextAdrSeq, entries };
+  return {
+    version: 1,
+    nextAdrSeq,
+    entries,
+    ...(runs !== undefined ? { runs } : {}),
+    ...(truncatedRunPeriods !== undefined ? { truncatedRunPeriods } : {}),
+    ...(acceptances !== undefined ? { acceptances } : {}),
+    ...(acceptanceHistoryComplete !== undefined ? { acceptanceHistoryComplete } : {}),
+  };
 }
 
 /**
@@ -850,7 +1010,88 @@ export function nextPromotionState(prev: PromotionState, report: PromotionReport
   // Only NEWLY allocated documents advance the sequence — a re-refused candidate rewrites its own
   // file, so counting every path would leave permanent gaps in the numbering.
   const seq = Number.isInteger(newlyAllocated) && (newlyAllocated as number) >= 0 ? (newlyAllocated as number) : Object.keys(adrSeqs).length;
-  return { version: 1, nextAdrSeq: Math.min(100_000, base.nextAdrSeq + seq), entries };
+  return {
+    version: 1,
+    nextAdrSeq: Math.min(100_000, base.nextAdrSeq + seq),
+    entries,
+    ...(base.runs !== undefined ? { runs: base.runs } : {}),
+    ...(base.truncatedRunPeriods !== undefined ? { truncatedRunPeriods: base.truncatedRunPeriods } : {}),
+    ...(base.acceptances !== undefined ? { acceptances: base.acceptances } : {}),
+    ...(base.acceptanceHistoryComplete !== undefined ? { acceptanceHistoryComplete: base.acceptanceHistoryComplete } : {}),
+  };
+}
+
+/** Add one prospective observation without changing any promotion decision or candidate report. */
+export function recordPromotionRunEvidence(
+  state: PromotionState,
+  report: PromotionReport,
+  nowTs: string,
+): PromotionState {
+  const base = normalizePromotionState(state);
+  if (!isOffsetIsoTimestamp(nowTs)) return base;
+  const source = Array.isArray(report?.candidates) ? report.candidates : [];
+  const complete = source.length <= MAX_PROMOTION_RUN_CANDIDATES;
+  const candidates: PromotionRunCandidateEvidence[] = source
+    .slice(0, MAX_PROMOTION_RUN_CANDIDATES)
+    .filter((candidate) => typeof candidate?.lessonId === 'string' && candidate.lessonId !== '')
+    .map((candidate) => ({
+      candidateAnchor: candidate.lessonId,
+      eligible: candidate.eligible === true,
+      ruleContentAnchor:
+        candidate.template !== null && candidate.params !== null
+          ? lessonRuleContentAnchor(candidate.template, candidate.params)
+          : null,
+      verdict: CANDIDATE_VERDICTS.includes(candidate.verdict) ? candidate.verdict : 'wait',
+    }));
+  const fingerprint = fnv1a32(JSON.stringify([nowTs, complete, candidates]));
+  const run: PromotionRunEvidence = {
+    runId: `${nowTs}#${fingerprint}`,
+    ts: nowTs,
+    complete,
+    candidates,
+  };
+  const runs = [...(base.runs ?? [])];
+  if (!runs.some((item) => item.runId === run.runId)) runs.push(run);
+  runs.sort((a, b) => Date.parse(a.ts) - Date.parse(b.ts) || a.runId.localeCompare(b.runId));
+  const removed = runs.slice(0, Math.max(0, runs.length - MAX_PROMOTION_RUN_EVIDENCE));
+  const retained = runs.slice(-MAX_PROMOTION_RUN_EVIDENCE);
+  const truncatedRunPeriods = [...new Set([
+    ...(base.truncatedRunPeriods ?? []),
+    ...removed.map((item) => new Date(Date.parse(item.ts)).toISOString().slice(0, 7)),
+  ])].sort().slice(-12);
+  const retainedAcceptances = base.acceptances ?? (base.runs ?? []).flatMap((priorRun) =>
+    priorRun.candidates
+      .filter((candidate) => candidate.verdict === 'promote' && candidate.ruleContentAnchor !== null)
+      .map((candidate) => ({ ruleContentAnchor: candidate.ruleContentAnchor!, acceptedTs: priorRun.ts })),
+  );
+  const byAnchor = new Map(retainedAcceptances.map((item) => [item.ruleContentAnchor, item]));
+  for (const candidate of candidates) {
+    if (candidate.verdict !== 'promote' || candidate.ruleContentAnchor === null) continue;
+    const prior = byAnchor.get(candidate.ruleContentAnchor);
+    if (prior === undefined || Date.parse(nowTs) < Date.parse(prior.acceptedTs)) {
+      byAnchor.set(candidate.ruleContentAnchor, { ruleContentAnchor: candidate.ruleContentAnchor, acceptedTs: nowTs });
+    }
+  }
+  const allAcceptances = [...byAnchor.values()]
+    .sort((a, b) => Date.parse(a.acceptedTs) - Date.parse(b.acceptedTs) || a.ruleContentAnchor.localeCompare(b.ruleContentAnchor));
+  const acceptanceOverflow = allAcceptances.length > MAX_PROMOTION_ACCEPTANCE_EVIDENCE;
+  const currentAcceptedRuleIds = new Set(report.candidates
+    .filter((candidate) => candidate.verdict === 'promote' && candidate.ruleId !== null)
+    .map((candidate) => candidate.ruleId!));
+  const hadUnknownAcceptedRules = base.acceptanceHistoryComplete === undefined &&
+    (Object.values(base.entries).some((entry) =>
+      entry.appliedTs !== undefined && !currentAcceptedRuleIds.has(entry.ruleId),
+    ) ||
+      (base.truncatedRunPeriods?.length ?? 0) > 0 ||
+      (base.runs ?? []).some((priorRun) => priorRun.complete !== true));
+  return {
+    ...base,
+    runs: retained,
+    truncatedRunPeriods,
+    acceptances: allAcceptances.slice(-MAX_PROMOTION_ACCEPTANCE_EVIDENCE),
+    acceptanceHistoryComplete:
+      base.acceptanceHistoryComplete !== false && !hadUnknownAcceptedRules && !acceptanceOverflow && complete,
+  };
 }
 
 // ── Rendering ───────────────────────────────────────────────────────────────────────────────────