Cumulative Advance/Decline Line: Recompute History Without Looking Ahead

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167

/** Causal, revision-aware Cumulative Advance/Decline Line. */

export type ResultStatus = "resolved" | "incomplete" | "ambiguous" | "unsupported";
export type Action = "upsert" | "cancel";

export interface ExpectedSession { session_sequence: number; session_date: string }
export interface SeriesContract {
  metric: "cumulative_issue_count_advance_decline_line" | string;
  series_id: string; continuity_id: string; venue_id: string; universe_id: string;
  calendar_id: string; session_type: string; comparison_basis: string;
  seed: number; seed_lineage_id: string; seed_effective_at: string;
  seed_available_at: string; expected_sessions: ExpectedSession[];
}
export interface BreadthEvent {
  event_id: string; ingest_sequence: number; revision_number: number;
  supersedes_event_id: string | null; action: Action; session_sequence: number;
  session_date: string; effective_at: string; available_at: string;
  series_id: string; continuity_id: string; venue_id: string; universe_id: string;
  calendar_id: string; session_type: string; comparison_basis: string;
  universe_snapshot_id: string; is_final: boolean;
  source_evidence_state: "ready" | "incomplete" | "ambiguous" | "unsupported";
  advances?: number; declines?: number; unchanged?: number; excluded?: number; unclassified?: number;
  universe_size?: number;
}
export interface BreadthLinePoint {
  session_sequence: number; session_date: string; event_id: string;
  revision_number: number; effective_at: string; available_at: string;
  advances: number; declines: number; unchanged: number; excluded: number;
  unclassified: number;
  universe_size: number; net_advances: number; cumulative_line: number;
  source_is_provisional: boolean; line_is_provisional: boolean;
  universe_snapshot_id: string;
  source_evidence_state: "ready";
}
export interface BreadthLineResult {
  status: ResultStatus; reasons: string[]; knowledge_cutoff: string; seed: number;
  points: BreadthLinePoint[]; missing_sessions: string[]; cancelled_sessions: string[];
  final_value: number | null; causal_prefix_diagnostic: BreadthLinePoint[];
  contains_provisional: boolean; ignored_future_event_count: number;
  recompute_from_session: string | null; blocked_from_session: string | null;
  metric: "cumulative_issue_count_advance_decline_line";
}

export class BreadthLineValidationError extends Error {
  constructor(message: string) { super(message); this.name = "BreadthLineValidationError"; }
}

const MAX_SAFE = Number.MAX_SAFE_INTEGER;
const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
const IDENTITY_FIELDS = ["series_id", "continuity_id", "venue_id", "universe_id", "calendar_id", "session_type", "comparison_basis"] as const;
const COUNT_FIELDS = ["advances", "declines", "unchanged", "excluded", "unclassified", "universe_size"] as const;

function text(value: unknown, field: string): string {
  if (typeof value !== "string" || value.trim() === "") throw new BreadthLineValidationError(`${field} must be a non-empty string.`);
  return value;
}
function timestamp(value: unknown, field: string): number {
  if (typeof value !== "string" || !/(Z|[+-]\d{2}:\d{2})$/.test(value) || Number.isNaN(Date.parse(value))) throw new BreadthLineValidationError(`${field} must be an RFC 3339 timestamp with offset.`);
  return Date.parse(value);
}
function date(value: unknown, field: string): string {
  if (typeof value !== "string" || !DATE_RE.test(value) || new Date(`${value}T00:00:00Z`).toISOString().slice(0, 10) !== value) throw new BreadthLineValidationError(`${field} must be a real YYYY-MM-DD date.`);
  return value;
}
function integer(value: unknown, field: string, nonnegative = false): number {
  if (!Number.isSafeInteger(value) || (nonnegative && (value as number) < 0)) throw new BreadthLineValidationError(`${field} must be a ${nonnegative ? "non-negative " : ""}safe integer.`);
  return value as number;
}
function base(status: ResultStatus, reasons: string[], cutoff: string, seed: number, ignored = 0): BreadthLineResult {
  return {status, reasons, knowledge_cutoff: cutoff, seed, points: [], final_value: null, causal_prefix_diagnostic: [], missing_sessions: [], cancelled_sessions: [], contains_provisional: false, ignored_future_event_count: ignored, recompute_from_session: null, blocked_from_session: null, metric: "cumulative_issue_count_advance_decline_line"};
}

export function calculateCumulativeAdvanceDeclineLine(contract: SeriesContract, events: BreadthEvent[], knowledgeCutoff: string): BreadthLineResult {
  if (contract === null || typeof contract !== "object") throw new BreadthLineValidationError("contract must be an object.");
  if (!Array.isArray(events)) throw new BreadthLineValidationError("events must be an ordered array.");
  const cutoff = timestamp(knowledgeCutoff, "knowledge_cutoff");
  const seed = integer(contract.seed, "seed");
  text(contract.seed_lineage_id, "seed_lineage_id");
  const seedEffective = timestamp(contract.seed_effective_at, "seed_effective_at");
  const seedAvailable = timestamp(contract.seed_available_at, "seed_available_at");
  if (seedAvailable < seedEffective) throw new BreadthLineValidationError("seed_available_at cannot precede seed_effective_at.");
  for (const field of IDENTITY_FIELDS) text(contract[field], field);
  if (contract.metric !== "cumulative_issue_count_advance_decline_line") return base("unsupported", ["unsupported_metric"], knowledgeCutoff, seed);
  if (!Array.isArray(contract.expected_sessions)) throw new BreadthLineValidationError("expected_sessions must be an ordered array.");
  const expected: ExpectedSession[] = [];
  let previousDate: string | null = null;
  for (let i = 0; i < contract.expected_sessions.length; i++) {
    const raw = contract.expected_sessions[i];
    const sequence = integer(raw.session_sequence, "session_sequence", true);
    const sessionDate = date(raw.session_date, "session_date");
    if (sequence !== i + 1 || (previousDate !== null && sessionDate <= previousDate)) return base("unsupported", ["expected_session_sequence_not_contiguous"], knowledgeCutoff, seed);
    expected.push({session_sequence: sequence, session_date: sessionDate}); previousDate = sessionDate;
  }
  const expectedByDate = new Map(expected.map(x => [x.session_date, x.session_sequence]));
  if (cutoff < seedAvailable) { const result = base("incomplete", ["seed_not_yet_available"], knowledgeCutoff, seed); result.blocked_from_session = expected[0]?.session_date ?? null; return result; }

  const validated: Array<BreadthEvent & {_available: number}> = [];
  let previousAvailable: number | null = null;
  const seen = new Set<string>(); let duplicate = false;
  const unsupported = new Set<string>();
  let ignored = 0;
  for (let i = 0; i < events.length; i++) {
    const raw = events[i]; if (raw === null || typeof raw !== "object") throw new BreadthLineValidationError("each event must be an object.");
    const event = structuredClone(raw) as BreadthEvent & {_available: number};
    const available = timestamp(event.available_at, "available_at");
    if (available > cutoff) { ignored++; continue; }
    const id = text(event.event_id, "event_id"); if (seen.has(id)) duplicate = true; seen.add(id);
    if (integer(event.ingest_sequence, "ingest_sequence", true) !== validated.length + 1) unsupported.add("event_sequence_not_contiguous");
    const effective = timestamp(event.effective_at, "effective_at");
    if (available < effective) throw new BreadthLineValidationError("available_at cannot precede effective_at.");
    if (previousAvailable !== null && available < previousAvailable) unsupported.add("events_not_in_ingest_order"); previousAvailable = available; event._available = available;
    event.session_date = date(event.session_date, "session_date"); event.session_sequence = integer(event.session_sequence, "session_sequence", true); event.revision_number = integer(event.revision_number, "revision_number", true);
    if (event.revision_number < 1) throw new BreadthLineValidationError("revision_number must be at least 1.");
    if (event.action !== "upsert" && event.action !== "cancel") throw new BreadthLineValidationError("action must be upsert or cancel.");
    if (event.supersedes_event_id !== null) text(event.supersedes_event_id, "supersedes_event_id");
    for (const field of IDENTITY_FIELDS) { text(event[field], field); if (event[field] !== contract[field]) unsupported.add("series_break_required"); }
    if (expectedByDate.get(event.session_date) !== event.session_sequence) unsupported.add("event_outside_expected_calendar");
    text(event.universe_snapshot_id, "universe_snapshot_id"); if (typeof event.is_final !== "boolean") throw new BreadthLineValidationError("is_final must be a boolean.");
    if (!["ready", "incomplete", "ambiguous", "unsupported"].includes(event.source_evidence_state)) throw new BreadthLineValidationError("source_evidence_state must be ready, incomplete, ambiguous, or unsupported.");
    if (event.action === "upsert") {
      const counts = Object.fromEntries(COUNT_FIELDS.map(f => [f, integer(event[f], f, true)])) as Record<typeof COUNT_FIELDS[number], number>;
      if (counts.advances + counts.declines + counts.unchanged + counts.excluded + counts.unclassified !== counts.universe_size) unsupported.add("unreconciled_issue_partition");
      if (event.source_evidence_state === "ready" && counts.unclassified !== 0) unsupported.add("ready_source_contains_unclassified_issues");
      Object.assign(event, counts);
    }
    validated.push(event);
  }
  if (unsupported.size) return base("unsupported", [...unsupported].sort(), knowledgeCutoff, seed);
  const visible = validated;
  if (duplicate) return base("ambiguous", ["duplicate_event_id"], knowledgeCutoff, seed, ignored);
  const grouped = new Map(expected.map(x => [x.session_date, [] as typeof visible]));
  for (const event of visible) grouped.get(event.session_date)!.push(event);
  const selected = new Map<string, typeof visible[number]>(); const corrected: string[] = [];
  for (const session of expected) {
    const chain = grouped.get(session.session_date)!; if (!chain.length) continue;
    for (let i = 0; i < chain.length; i++) {
      const requiredParent = i === 0 ? null : chain[i - 1].event_id;
      if (chain[i].revision_number !== i + 1 || chain[i].supersedes_event_id !== requiredParent) return base("ambiguous", [`non_unique_revision_lineage:${session.session_date}`], knowledgeCutoff, seed, ignored);
    }
    selected.set(session.session_date, chain.at(-1)!); if (chain.length > 1) corrected.push(session.session_date);
  }
  let running = seed; let provisionalSeen = false; let blocked: string | null = null;
  let sourceBlockStatus: ResultStatus | null = null;
  const points: BreadthLinePoint[] = []; const missing: string[] = []; const cancelled: string[] = []; const reasons: string[] = [];
  for (const session of expected) {
    const event = selected.get(session.session_date);
    if (!event) { missing.push(session.session_date); blocked ??= session.session_date; continue; }
    if (event.action === "cancel") { cancelled.push(session.session_date); blocked ??= session.session_date; continue; }
    const sourceState = event.source_evidence_state;
    if (sourceState !== "ready") {
      blocked ??= session.session_date; reasons.push(`source_evidence_${sourceState}:${session.session_date}`);
      if (sourceState === "unsupported") sourceBlockStatus = "unsupported";
      else if (sourceState === "ambiguous" && sourceBlockStatus !== "unsupported") sourceBlockStatus = "ambiguous";
      else if (sourceBlockStatus === null) sourceBlockStatus = "incomplete";
      continue;
    }
    if (blocked !== null) continue;
    const advances = event.advances!; const declines = event.declines!; const net = advances - declines; running = integer(running + net, "cumulative_line");
    const sourceProvisional = !event.is_final; provisionalSeen ||= sourceProvisional;
    points.push({session_sequence: session.session_sequence, session_date: session.session_date, event_id: event.event_id, revision_number: event.revision_number, effective_at: event.effective_at, available_at: event.available_at, advances, declines, unchanged: event.unchanged!, excluded: event.excluded!, unclassified: event.unclassified!, universe_size: event.universe_size!, net_advances: net, cumulative_line: running, source_is_provisional: sourceProvisional, line_is_provisional: provisionalSeen, universe_snapshot_id: event.universe_snapshot_id, source_evidence_state: "ready"});
  }
  if (missing.length) reasons.push("missing_expected_session"); if (cancelled.length) reasons.push("cancelled_session"); if (provisionalSeen) reasons.push("provisional_source_in_suffix");
  const status: ResultStatus = sourceBlockStatus ?? (reasons.length ? "incomplete" : "resolved");
  const publishable = status === "resolved";
  return {status, reasons, knowledge_cutoff: knowledgeCutoff, seed, points: publishable ? points : [], final_value: publishable ? (points.at(-1)?.cumulative_line ?? seed) : null, causal_prefix_diagnostic: publishable ? [] : points, missing_sessions: missing, cancelled_sessions: cancelled, contains_provisional: provisionalSeen, ignored_future_event_count: ignored, recompute_from_session: corrected.length ? [...corrected].sort()[0] : null, blocked_from_session: blocked, metric: "cumulative_issue_count_advance_decline_line"};
}