opencandle 0.10.0 → 0.11.1

package/src/infra/cache.ts

@@ -12,21 +12,27 @@ export interface StaleResult<T> {
   cachedAt: number;
 }
 
-interface StaleMetadata {
-  stale: boolean;
+interface CacheMetadata {
+  status: "none" | "cached" | "stale";
   cachedAt: number;
 }
 
-const staleMetadataStorage = new AsyncLocalStorage<StaleMetadata>();
+const cacheMetadataStorage = new AsyncLocalStorage<CacheMetadata>();
 
-export async function runWithStaleMetadata<T>(
-  fn: () => Promise<T>,
-): Promise<{ value: T; stale?: { cachedAt: number } }> {
-  const metadata: StaleMetadata = { stale: false, cachedAt: 0 };
-  const value = await staleMetadataStorage.run(metadata, fn);
+export async function runWithStaleMetadata<T>(fn: () => Promise<T>): Promise<{
+  value: T;
+  cache?: { status: "cached" | "stale"; cachedAt: number };
+  stale?: { cachedAt: number };
+}> {
+  const metadata: CacheMetadata = { status: "none", cachedAt: 0 };
+  const value = await cacheMetadataStorage.run(metadata, fn);
   return {
     value,
-    stale: metadata.stale ? { cachedAt: metadata.cachedAt } : undefined,
+    cache:
+      metadata.status === "cached" || metadata.status === "stale"
+        ? { status: metadata.status, cachedAt: metadata.cachedAt }
+        : undefined,
+    stale: metadata.status === "stale" ? { cachedAt: metadata.cachedAt } : undefined,
   };
 }
 
@@ -37,6 +43,11 @@ export class Cache {
     const entry = this.store.get(key);
     if (!entry) return undefined;
     if (Date.now() > entry.expiresAt) return undefined;
+    const metadata = cacheMetadataStorage.getStore();
+    if (metadata && metadata.status === "none") {
+      metadata.status = "cached";
+      metadata.cachedAt = entry.cachedAt;
+    }
     return entry.value as T;
   }
 
@@ -54,9 +65,9 @@ export class Cache {
       return undefined;
     }
 
-    const metadata = staleMetadataStorage.getStore();
+    const metadata = cacheMetadataStorage.getStore();
     if (metadata) {
-      metadata.stale = true;
+      metadata.status = "stale";
       metadata.cachedAt = entry.cachedAt;
     }
     return { value: entry.value as T, stale: true, cachedAt: entry.cachedAt };
@@ -98,6 +109,7 @@ export const TTL = {
   CRUMB: 900_000, // 15 minutes
   WEB_SEARCH: 300_000, // 5 minutes
   FINNHUB_NEWS: 300_000, // 5 minutes
+  PREDICTION_MARKETS: 300_000, // 5 minutes
 } as const;
 
 // Stale limits — how long past TTL expiry a cached value is still useful as fallback
@@ -111,4 +123,5 @@ export const STALE_LIMIT = {
   SCREENER: 15 * 60_000, // 15 minutes
   WEB_SEARCH: 3_600_000, // 1 hour
   FINNHUB_NEWS: 3_600_000, // 1 hour
+  PREDICTION_MARKETS: 3_600_000, // 1 hour
 } as const;

package/src/infra/freshness.ts

@@ -0,0 +1,165 @@
+import {
+  classifyMarketStatusAt,
+  lastTradingDay,
+  localDateTimeParts,
+  type MarketSession,
+} from "./market-calendar.js";
+
+export interface FreshnessStamp {
+  fetchedAt: string;
+  providerDataAt?: string;
+  providerDataDate?: string;
+  cacheStatus: "live" | "cached" | "stale";
+  cachedAt?: string;
+  marketSession: MarketSession;
+  dataDelayMs?: number;
+  isStaleForSession: boolean;
+}
+
+export function buildFreshnessStamp(input: {
+  asOf?: string | number | Date;
+  cached?: boolean;
+  stale?: boolean;
+  cachedAt?: string;
+  dataDelayMs?: number;
+  now?: Date;
+  assetClass?: "equity" | "crypto";
+}): FreshnessStamp {
+  const now = input.now ?? new Date();
+  const parsedAsOf = normalizeAsOf(input.asOf);
+  const fetchedAt = now.toISOString();
+  const cacheStatus = input.stale ? "stale" : input.cached ? "cached" : "live";
+  const marketSession = input.assetClass === "crypto" ? "unknown" : classifyMarketStatusAt(now);
+  const cachedAt = input.cachedAt ? normalizeDate(input.cachedAt)?.toISOString() : undefined;
+  const providerDataAt = parsedAsOf?.date.toISOString();
+  const providerDataDate = parsedAsOf?.dateOnly;
+  const isStaleForSession =
+    input.assetClass === "crypto"
+      ? isCryptoStale(parsedAsOf?.date, cachedAt, now, cacheStatus)
+      : isEquityStale(parsedAsOf, cacheStatus, now);
+
+  return {
+    fetchedAt,
+    providerDataAt,
+    providerDataDate,
+    cacheStatus,
+    cachedAt,
+    marketSession,
+    dataDelayMs: input.dataDelayMs,
+    isStaleForSession,
+  };
+}
+
+export function formatAsOfLine(stamp: FreshnessStamp): string {
+  if (stamp.isStaleForSession && stamp.providerDataAt) {
+    const date = stamp.providerDataDate ?? formatEtDate(new Date(stamp.providerDataAt));
+    const parenthetical = staleSessionParenthetical(stamp.marketSession);
+    const cached = stamp.cachedAt
+      ? ` Cached from ${formatEtDateTime(new Date(stamp.cachedAt))} ET.`
+      : "";
+    return `Last available price as of ${date}${parenthetical}. This is not a live quote.${cached}`;
+  }
+
+  if (stamp.cacheStatus === "stale" && stamp.cachedAt) {
+    const notLive = stamp.isStaleForSession ? " This is not a live quote." : "";
+    return `Using cached data from ${formatEtDateTime(new Date(stamp.cachedAt))} ET (provider unavailable).${notLive}`;
+  }
+
+  if (stamp.providerDataAt || stamp.dataDelayMs !== undefined) {
+    const reference = stamp.providerDataAt ?? stamp.cachedAt ?? stamp.fetchedAt;
+    const asOf = stamp.providerDataDate ?? formatEtDateTime(new Date(reference));
+    if (stamp.dataDelayMs !== undefined)
+      return `As of ${asOf} ET (~${Math.round(stamp.dataDelayMs / 60_000)}m delayed).`;
+    return `As of ${asOf} ET (${marketSessionLabel(stamp.marketSession)}).`;
+  }
+
+  return `As of ${formatEtDateTime(new Date(stamp.fetchedAt))} ET (${marketSessionLabel(stamp.marketSession)}).`;
+}
+
+function normalizeAsOf(
+  asOf: string | number | Date | undefined,
+): { date: Date; dateOnly?: string } | undefined {
+  if (asOf === undefined) return undefined;
+  if (asOf instanceof Date) return Number.isNaN(asOf.getTime()) ? undefined : { date: asOf };
+  if (typeof asOf === "number") {
+    const milliseconds = asOf < 10_000_000_000 ? asOf * 1000 : asOf;
+    const date = new Date(milliseconds);
+    return Number.isNaN(date.getTime()) ? undefined : { date };
+  }
+  if (/^\d{4}-\d{2}-\d{2}$/.test(asOf)) {
+    const date = new Date(`${asOf}T00:00:00.000Z`);
+    return Number.isNaN(date.getTime()) ? undefined : { date, dateOnly: asOf };
+  }
+  const date = new Date(asOf);
+  return Number.isNaN(date.getTime()) ? undefined : { date };
+}
+
+function normalizeDate(value: string): Date | undefined {
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? undefined : date;
+}
+
+function isEquityStale(
+  parsedAsOf: { date: Date; dateOnly?: string } | undefined,
+  cacheStatus: FreshnessStamp["cacheStatus"],
+  now: Date,
+): boolean {
+  if (!parsedAsOf) return cacheStatus === "stale";
+  const localNow = localDateTimeParts(now, "America/New_York");
+  const providerTradingDate =
+    parsedAsOf.dateOnly ?? localDateTimeParts(parsedAsOf.date, "America/New_York").date;
+  const marketSession = classifyMarketStatusAt(now);
+  const requiredTradingDate =
+    marketSession === "open" ||
+    marketSession === "after_close" ||
+    marketSession === "closed_after_hours"
+      ? localNow.date
+      : lastTradingDay(localNow.date);
+  return providerTradingDate < requiredTradingDate;
+}
+
+function isCryptoStale(
+  providerDate: Date | undefined,
+  cachedAt: string | undefined,
+  now: Date,
+  cacheStatus: FreshnessStamp["cacheStatus"],
+): boolean {
+  const reference =
+    providerDate ?? (cacheStatus === "stale" && cachedAt ? new Date(cachedAt) : undefined);
+  if (!reference) return cacheStatus === "stale";
+  return now.getTime() - reference.getTime() > 15 * 60_000;
+}
+
+function formatEtDate(date: Date): string {
+  return localDateTimeParts(date, "America/New_York").date;
+}
+
+function formatEtDateTime(date: Date): string {
+  const parts = localDateTimeParts(date, "America/New_York");
+  return `${parts.date} ${parts.time}`;
+}
+
+function staleSessionParenthetical(marketSession: MarketSession): string {
+  if (marketSession === "closed_weekend") return " (market closed — weekend)";
+  if (marketSession === "closed_holiday") return " (market closed — holiday)";
+  return "";
+}
+
+function marketSessionLabel(marketSession: MarketSession): string {
+  switch (marketSession) {
+    case "open":
+      return "market open";
+    case "pre_market":
+      return "pre-market";
+    case "closed_weekend":
+      return "market closed — weekend";
+    case "closed_holiday":
+      return "market closed — holiday";
+    case "after_close":
+      return "after close";
+    case "closed_after_hours":
+      return "market closed";
+    case "unknown":
+      return "market session unknown";
+  }
+}

package/src/infra/market-calendar.ts

@@ -0,0 +1,193 @@
+export type MarketSession =
+  | "closed_weekend"
+  | "closed_holiday"
+  | "pre_market"
+  | "open"
+  | "after_close"
+  | "closed_after_hours"
+  | "unknown";
+
+export interface LocalDateTimeParts {
+  date: string;
+  time: string;
+  weekday: string;
+  minutesSinceMidnight: number;
+}
+
+export const KNOWN_US_MARKET_HOLIDAYS: Record<string, string> = new Proxy(
+  {} as Record<string, string>,
+  {
+    get(_target, property) {
+      return typeof property === "string" ? marketHolidayName(property) : undefined;
+    },
+    has(_target, property) {
+      return typeof property === "string" && marketHolidayName(property) !== undefined;
+    },
+  },
+);
+
+export function marketHolidayName(key: string): string | undefined {
+  const date = dateFromKey(key);
+  const year = date.getUTCFullYear();
+  for (const candidateYear of [year - 1, year, year + 1]) {
+    const holiday = marketHolidaysForYear(candidateYear).find((entry) => entry.date === key);
+    if (holiday) return holiday.name;
+  }
+  return undefined;
+}
+
+export function classifyMarketStatus(
+  local: LocalDateTimeParts,
+  isWeekend: boolean,
+  isMarketHoliday: boolean,
+  temporalReferences: string[],
+): Exclude<MarketSession, "unknown"> {
+  if (isWeekend) return "closed_weekend";
+  if (isMarketHoliday) return "closed_holiday";
+  if (local.minutesSinceMidnight < 9 * 60 + 30) return "pre_market";
+  if (local.minutesSinceMidnight < 16 * 60) return "open";
+  if (temporalReferences.includes("after_close")) return "after_close";
+  return "closed_after_hours";
+}
+
+export function classifyMarketStatusAt(now: Date): MarketSession {
+  const local = localDateTimeParts(now, "America/New_York");
+  return classifyMarketStatus(
+    local,
+    local.weekday === "Sat" || local.weekday === "Sun",
+    marketHolidayName(local.date) !== undefined,
+    [],
+  );
+}
+
+export function localDateTimeParts(date: Date, timezone: string): LocalDateTimeParts {
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    timeZone: timezone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+    weekday: "short",
+  });
+  const parts = formatter.formatToParts(date).reduce<Record<string, string>>((acc, part) => {
+    acc[part.type] = part.value;
+    return acc;
+  }, {});
+  const hour = Number(parts.hour);
+  const minute = Number(parts.minute);
+  return {
+    date: `${parts.year}-${parts.month}-${parts.day}`,
+    time: `${parts.hour}:${parts.minute}`,
+    weekday: parts.weekday ?? "",
+    minutesSinceMidnight: hour * 60 + minute,
+  };
+}
+
+export function lastTradingDay(localDate: string): string {
+  let cursor = dateFromKey(localDate);
+  do {
+    cursor = addDays(cursor, -1);
+  } while (isWeekendOrKnownHoliday(dateKey(cursor)));
+  return dateKey(cursor);
+}
+
+export function isWeekendOrKnownHoliday(key: string): boolean {
+  const date = dateFromKey(key);
+  const day = date.getUTCDay();
+  return day === 0 || day === 6 || marketHolidayName(key) !== undefined;
+}
+
+function marketHolidaysForYear(year: number): Array<{ date: string; name: string }> {
+  return [
+    observedFixedHoliday(year, 1, 1, "New Year's Day"),
+    nthWeekdayHoliday(year, 1, 1, 3, "Martin Luther King Jr. Day"),
+    nthWeekdayHoliday(year, 2, 1, 3, "Washington's Birthday"),
+    { date: dateKey(addDays(easterDate(year), -2)), name: "Good Friday" },
+    lastWeekdayHoliday(year, 5, 1, "Memorial Day"),
+    observedFixedHoliday(year, 6, 19, "Juneteenth"),
+    observedFixedHoliday(year, 7, 4, "Independence Day"),
+    nthWeekdayHoliday(year, 9, 1, 1, "Labor Day"),
+    nthWeekdayHoliday(year, 11, 4, 4, "Thanksgiving Day"),
+    observedFixedHoliday(year, 12, 25, "Christmas Day"),
+  ];
+}
+
+function observedFixedHoliday(
+  year: number,
+  month: number,
+  day: number,
+  name: string,
+): {
+  date: string;
+  name: string;
+} {
+  const actual = new Date(Date.UTC(year, month - 1, day));
+  const weekday = actual.getUTCDay();
+  const observed =
+    weekday === 0 ? addDays(actual, 1) : weekday === 6 ? addDays(actual, -1) : actual;
+  return {
+    date: dateKey(observed),
+    name: observed.getTime() === actual.getTime() ? name : `${name} observed`,
+  };
+}
+
+function nthWeekdayHoliday(
+  year: number,
+  month: number,
+  weekday: number,
+  occurrence: number,
+  name: string,
+): { date: string; name: string } {
+  const first = new Date(Date.UTC(year, month - 1, 1));
+  const offset = (weekday - first.getUTCDay() + 7) % 7;
+  return { date: dateKey(addDays(first, offset + (occurrence - 1) * 7)), name };
+}
+
+function lastWeekdayHoliday(
+  year: number,
+  month: number,
+  weekday: number,
+  name: string,
+): { date: string; name: string } {
+  const last = new Date(Date.UTC(year, month, 0));
+  const offset = (last.getUTCDay() - weekday + 7) % 7;
+  return { date: dateKey(addDays(last, -offset)), name };
+}
+
+function easterDate(year: number): Date {
+  const a = year % 19;
+  const b = Math.floor(year / 100);
+  const c = year % 100;
+  const d = Math.floor(b / 4);
+  const e = b % 4;
+  const f = Math.floor((b + 8) / 25);
+  const g = Math.floor((b - f + 1) / 3);
+  const h = (19 * a + b - d - g + 15) % 30;
+  const i = Math.floor(c / 4);
+  const k = c % 4;
+  const l = (32 + 2 * e + 2 * i - h - k) % 7;
+  const m = Math.floor((a + 11 * h + 22 * l) / 451);
+  const easterMonth = Math.floor((h + l - 7 * m + 114) / 31);
+  const easterDay = ((h + l - 7 * m + 114) % 31) + 1;
+  return new Date(Date.UTC(year, easterMonth - 1, easterDay));
+}
+
+function dateFromKey(key: string): Date {
+  const [year, month, day] = key.split("-").map(Number);
+  return new Date(Date.UTC(year, month - 1, day));
+}
+
+function addDays(date: Date, days: number): Date {
+  const next = new Date(date);
+  next.setUTCDate(next.getUTCDate() + days);
+  return next;
+}
+
+function dateKey(date: Date): string {
+  const year = date.getUTCFullYear();
+  const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(date.getUTCDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}

package/src/infra/rate-limiter.ts

@@ -72,5 +72,6 @@ rateLimiter.configure("exa", 5, 0.1); // 5 req, ~6 req/min
 rateLimiter.configure("finnhub", 60, 1); // 60 req/min (free tier)
 // TradingView scanner is undocumented; keep usage batch-first and paced.
 rateLimiter.configure("tradingview", 5, 1); // 5 burst, 1 req/s sustained
+rateLimiter.configure("polymarket", 10, 5); // 10 burst, 5 req/s sustained
 // SEC EDGAR fair-access guideline is 10 req/s; stay below it.
 rateLimiter.configure("sec_edgar", 5, 5); // 5 burst, 5 req/s sustained

package/src/market-state/daily-report.ts

@@ -17,25 +17,18 @@ export interface DailyWatchlistReport {
   dataGaps: string[];
 }
 
-export function getOrCreateDefaultWatchlistReportTemplate(
+// Returns the configured default-watchlist morning template if one exists.
+// Manual report runs must never create a schedule template as a side effect;
+// only the explicit configure flow stores schedule intent.
+export function findDefaultWatchlistReportTemplate(
   service: MarketStateService,
-): ReportTemplateRecord {
-  const existing = service
+): ReportTemplateRecord | undefined {
+  return service
     .listReportTemplates()
     .find(
       (template) =>
         template.reportType === "watchlist_daily" && targetsDefaultWatchlist(template.configJson),
     );
-  if (existing) return existing;
-  return service.createReportTemplate({
-    name: "Morning watchlist",
-    reportType: "watchlist_daily",
-    cadence: "daily",
-    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
-    localTime: "08:00",
-    config: { targets: { default_watchlist: true } },
-    enabled: true,
-  });
 }
 
 export async function recordDailyWatchlistReportRun(
@@ -129,9 +122,6 @@ export async function generateDailyWatchlistReport(
     `Recent alerts`,
     `  ${service.listAlertEvents().length} recorded alert event(s).`,
     ``,
-    `Technical snapshot`,
-    `  Deferred unless quote/history data is available through a later section builder.`,
-    ``,
     `Data gaps`,
     ...dataGapLines,
   ];

package/src/market-state/service.ts

@@ -1,8 +1,6 @@
 import type Database from "better-sqlite3";
 
 export type AssetType = "equity" | "etf" | "fund" | "crypto" | "index" | "option" | "unknown";
-export type PredictionDirection = "bullish" | "bearish" | "neutral";
-export type PredictionStatus = "open" | "resolved" | "expired" | "cancelled";
 export type AlertScopeType = "instrument" | "watchlist" | "portfolio";
 
 export interface InstrumentInput {
@@ -100,23 +98,6 @@ export interface PortfolioLotRecord {
   updatedAt: string;
 }
 
-export interface PredictionRecord {
-  id: number;
-  instrumentId: number;
-  symbol: string;
-  direction: PredictionDirection;
-  conviction: number;
-  entryPrice: number;
-  targetPrice: number | null;
-  openedAt: string;
-  expiresAt: string;
-  status: PredictionStatus;
-  resolvedAt: string | null;
-  resultJson: string | null;
-  createdAt: string;
-  updatedAt: string;
-}
-
 export interface AlertRuleRecord {
   id: number;
   scopeType: AlertScopeType;
@@ -337,23 +318,6 @@ type PortfolioLotRow = {
   updated_at: string;
 };
 
-type PredictionRow = {
-  id: number;
-  instrument_id: number;
-  symbol: string;
-  direction: PredictionDirection;
-  conviction: number;
-  entry_price: number;
-  target_price: number | null;
-  opened_at: string;
-  expires_at: string;
-  status: PredictionStatus;
-  resolved_at: string | null;
-  result_json: string | null;
-  created_at: string;
-  updated_at: string;
-};
-
 type AlertRuleRow = {
   id: number;
   scope_type: AlertScopeType;
@@ -877,75 +841,6 @@ export class MarketStateService {
     });
   }
 
-  recordPrediction(params: {
-    instrument: InstrumentInput;
-    direction: PredictionDirection;
-    conviction: number;
-    entryPrice: number;
-    targetPrice?: number;
-    timeframeDays: number;
-    now?: Date;
-  }): PredictionRecord {
-    const tx = this.db.transaction(() => {
-      const instrument = this.upsertInstrument(params.instrument);
-      const opened = params.now ?? new Date();
-      const expires = new Date(opened);
-      expires.setDate(expires.getDate() + params.timeframeDays);
-      const nowIso = opened.toISOString();
-      const result = this.db
-        .prepare(
-          `INSERT INTO prediction_records (
-             instrument_id, direction, conviction, entry_price, target_price,
-             opened_at, expires_at, status, created_at, updated_at
-           )
-           VALUES (?, ?, ?, ?, ?, ?, ?, 'open', ?, ?)`,
-        )
-        .run(
-          instrument.id,
-          params.direction,
-          params.conviction,
-          params.entryPrice,
-          params.targetPrice ?? null,
-          nowIso,
-          expires.toISOString(),
-          nowIso,
-          nowIso,
-        );
-      return Number(result.lastInsertRowid);
-    });
-
-    return this.getPrediction(tx());
-  }
-
-  listPredictions(): PredictionRecord[] {
-    const rows = this.db
-      .prepare(
-        `SELECT pr.*, i.symbol
-         FROM prediction_records pr
-         JOIN instruments i ON i.id = pr.instrument_id
-         ORDER BY pr.opened_at, pr.id`,
-      )
-      .all() as PredictionRow[];
-    return rows.map(mapPrediction);
-  }
-
-  updatePredictionOutcome(params: {
-    id: number;
-    status: Exclude<PredictionStatus, "open">;
-    resolvedAt: string;
-    result: unknown;
-  }): PredictionRecord {
-    const now = new Date().toISOString();
-    this.db
-      .prepare(
-        `UPDATE prediction_records
-         SET status = ?, resolved_at = ?, result_json = ?, updated_at = ?
-         WHERE id = ?`,
-      )
-      .run(params.status, params.resolvedAt, JSON.stringify(params.result), now, params.id);
-    return this.getPrediction(params.id);
-  }
-
   createAlertRule(params: {
     scopeType: AlertScopeType;
     scopeId?: number;
@@ -1998,18 +1893,6 @@ export class MarketStateService {
     return row == null ? null : mapPortfolioLot(row);
   }
 
-  private getPrediction(id: number): PredictionRecord {
-    const row = this.db
-      .prepare(
-        `SELECT pr.*, i.symbol
-         FROM prediction_records pr
-         JOIN instruments i ON i.id = pr.instrument_id
-         WHERE pr.id = ?`,
-      )
-      .get(id) as PredictionRow;
-    return mapPrediction(row);
-  }
-
   getAlertRule(id: number): AlertRuleRecord {
     const row = this.db.prepare("SELECT * FROM alert_rules WHERE id = ?").get(id) as AlertRuleRow;
     return mapAlertRule(row);
@@ -2118,25 +2001,6 @@ function mapPortfolioLot(row: PortfolioLotRow): PortfolioLotRecord {
   };
 }
 
-function mapPrediction(row: PredictionRow): PredictionRecord {
-  return {
-    id: row.id,
-    instrumentId: row.instrument_id,
-    symbol: row.symbol,
-    direction: row.direction,
-    conviction: row.conviction,
-    entryPrice: row.entry_price,
-    targetPrice: row.target_price,
-    openedAt: row.opened_at,
-    expiresAt: row.expires_at,
-    status: row.status,
-    resolvedAt: row.resolved_at,
-    resultJson: row.result_json,
-    createdAt: row.created_at,
-    updatedAt: row.updated_at,
-  };
-}
-
 function mapAlertRule(row: AlertRuleRow): AlertRuleRecord {
   return {
     id: row.id,