@motionstudies/data 0.1.0-alpha.27 → 0.1.0-alpha.29

package/README.md

@@ -194,6 +194,14 @@ Consumers supply remaining `stops` in journey order and update them with playbac
 
 The required `note` explains provenance. Optional `status`, `statusTone`, `clockLabel`, localized `labels`, `loading`, `error` and `onRetry` follow the consumer's data; the component never manufactures an on-time status. Loading and errors hide the calling points. Stop selection is controlled through stable call IDs and does not alter playback or clear when a call leaves the list. All supplied calls are shown, with wrapping names and container-based compact layouts. The lab exercises advance/rewind, unknown destinations/times, localization, disruption, recovery and narrow widths. Edition adoption requires its own package upgrade and data adapter.
 
+## Feed observability
+
+`@motionstudies/data/feed-observability` validates versioned feed registries, operational events and health reports. `@motionstudies/data/recorder-observability` projects a recorder status snapshot into that shared contract, rechecking freshness against the observer's clock and omitting private paths, PIDs and raw errors. Both are pure functions with no acquisition, storage or notification side effects. The source repository's `docs/FEED-OBSERVABILITY.md` describes the read-only CLI, example registry, states and evidence limits. Registry daily schedules remain declarative; explicit dated evidence plans and incident history are available through the Node adapters below.
+
+`@motionstudies/data/recorder-evidence` reads explicit dated local journal/close-out and release targets, verifies their hashes and identities, and assesses missing expected outputs against deadlines. `@motionstudies/data/feed-incidents` persists debounced incident transitions with replay protection, atomic checksummed state, bounded retention and fail-closed capacity limits. These two modules require Node. See `docs/FEED-INCIDENTS.md` for CLI opt-in flags and operational limits; neither module installs a scheduler or sends notifications.
+
+`@motionstudies/data/release` checks versioned release handoffs in Node or a browser: safe file descriptors (`{ path, sha256, bytes }`), every descriptor in a manifest whatever its layout, kind and schema, and fetched bytes through Web Crypto. `@motionstudies/data/release-files` opens a release directory in Node, optionally pinned to its manifest digest, reads only described files without escaping the directory, and verifies a whole release within a byte budget. Format meaning stays with each format's reader. See the source repository's `docs/RELEASE-CONTRACT.md`.
+
 ## Optional live airport feed
 
 `AirportBoard` from `@motionstudies/web/components/AirportBoard` adds Study/Now controls around an existing `AirportHeroCard` configuration. Pass `studyCard` with the usual card props and `live={{ baseUrl, edition, airport }}` for the shared service. Import `airport-hero-card.css`. `labels` localizes the wrapper's control and availability messages. The lower-level `useAirportFeed` hook and core `domain/live-airport` contract are also public exports.

package/feed-expectations.d.mts

@@ -0,0 +1,3 @@
+export interface DailyExpectation { serviceDate: string; deadlineAt: string; nextDeadlineAt: string }
+/** Repeated local minutes use their later occurrence; missing minutes use the next valid minute. */
+export function dailyFeedExpectation(schedule: { timeZone: string; deadline: string }, now?: number): DailyExpectation

package/feed-expectations.mjs

@@ -0,0 +1,33 @@
+import { readOperationalTime } from './feed-observability.mjs'
+
+const shift = (date, days) => new Date(Date.parse(`${date}T00:00:00Z`) + days * 86400000).toISOString().slice(0, 10)
+function formatter(timeZone) {
+  return new Intl.DateTimeFormat('en-CA', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', hourCycle: 'h23' })
+}
+function wall(format, ms) {
+  const p = Object.fromEntries(format.formatToParts(ms).map(p => [p.type, p.value]))
+  return `${p.year}-${p.month}-${p.day}T${p.hour}:${p.minute}`
+}
+/** Latest occurrence of a repeated local minute; first valid minute after a DST gap. */
+function deadlineAt(date, deadline, format) {
+  const target = `${date}T${deadline}`, nominal = Date.parse(`${target}:00Z`)
+  let exact = null, next = null
+  for (let ms = nominal - 18 * 3600000; ms <= nominal + 18 * 3600000; ms += 60000) {
+    const local = wall(format, ms)
+    if (local === target) exact = ms
+    if (local.slice(0, 10) === date && local > target && (!next || local < next.local)) next = { local, ms }
+  }
+  const value = exact ?? next?.ms
+  if (value === undefined) throw new Error('Local deadline does not exist on this date')
+  return value
+}
+/** Latest completed service date whose following-day deadline has passed. */
+export function dailyFeedExpectation({ timeZone, deadline }, now = Date.now()) {
+  if (typeof timeZone !== 'string' || timeZone.length > 80 || !/^(?:[01]\d|2[0-3]):[0-5]\d$/.test(deadline)) throw new Error('Invalid daily expectation')
+  readOperationalTime(new Date(now).toISOString())
+  const format = formatter(timeZone), today = wall(format, now).slice(0, 10)
+  const todayDeadline = deadlineAt(today, deadline, format), dueToday = now >= todayDeadline
+  const dueDate = dueToday ? today : shift(today, -1)
+  return { serviceDate: shift(dueDate, -1), deadlineAt: new Date(dueToday ? todayDeadline : deadlineAt(dueDate, deadline, format)).toISOString(),
+    nextDeadlineAt: new Date(dueToday ? deadlineAt(shift(today, 1), deadline, format) : todayDeadline).toISOString() }
+}

package/feed-incidents.d.mts

@@ -0,0 +1,44 @@
+import type { FeedHealth, OperationalState } from './feed-observability.mjs'
+export interface IncidentPolicy { openAfterSeconds: number; recoverAfterSeconds: number; retentionDays: number; maxEvents: number }
+export declare const INCIDENT_POLICY: Readonly<IncidentPolicy>
+export interface IncidentEvent {
+  id: string
+  incidentId: string
+  key: string
+  feedId: string | null
+  stageId: string
+  firstDetectedAt: string
+  at: string
+  transition: 'opened' | 'updated' | 'recovered'
+  state: OperationalState
+  reasons: string[]
+}
+export interface ActiveIncident {
+  incidentId: string
+  key: string
+  feedId: string | null
+  stageId: string
+  firstDetectedAt: string
+  openedAt: string
+  lastObservedAt: string
+  state: OperationalState
+  reasons: string[]
+  recoveryStartedAt?: string
+  recoveryProducerAt?: string
+}
+export interface IncidentState {
+  schemaVersion: 1
+  kind: 'feed-incident-state'
+  registryId: string
+  producerId: string
+  policy: IncidentPolicy
+  lastObservedAt: string
+  lastReportId: string
+  report: FeedHealth
+  active: Record<string, ActiveIncident>
+  pending: Record<string, { since: string }>
+  events: IncidentEvent[]
+  prunedEvents: number
+}
+export function readIncidentStore(root: string): Promise<IncidentState>
+export function updateIncidentStore(root: string, registry: unknown, report: unknown, options?: { policy?: Partial<IncidentPolicy>; now?: number }): Promise<{ state: IncidentState; changed: boolean; events: IncidentEvent[] }>

package/feed-incidents.mjs

@@ -0,0 +1,148 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { mkdir, lstat, open, rename, rm } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { hostname } from 'node:os'
+import { readFeedRegistry, readFeedHealth, readOperationalTime } from './feed-observability.mjs'
+import { readOperationalFile } from './operational-files.mjs'
+
+const MAX_BYTES = 8 * 1024 * 1024
+export const INCIDENT_POLICY = Object.freeze({ openAfterSeconds: 120, recoverAfterSeconds: 60, retentionDays: 180, maxEvents: 10000 })
+const canonical = value => JSON.stringify(value, (_, v) => v && typeof v === 'object' && !Array.isArray(v) ? Object.fromEntries(Object.keys(v).sort().map(k => [k, v[k]])) : v)
+const hash = value => createHash('sha256').update(value).digest('hex')
+const notInstrumented = new Set(['upload-evidence-unavailable', 'stage-evidence-unavailable', 'capture-threshold-unconfigured', 'normalization-threshold-unconfigured', 'analytics-threshold-unconfigured'])
+function policy(value) {
+  const p = { ...INCIDENT_POLICY, ...value }
+  if (Object.keys(p).some(k => !Object.hasOwn(INCIDENT_POLICY, k)) || Object.values(p).some(n => !Number.isSafeInteger(n) || n < 0) || p.openAfterSeconds > 86400 || p.recoverAfterSeconds > 86400 || p.retentionDays < 1 || p.retentionDays > 3650 || p.maxEvents < 1 || p.maxEvents > 20000) throw new Error('Invalid incident policy')
+  return p
+}
+function validateState(state) {
+  if (!state || state.schemaVersion !== 1 || state.kind !== 'feed-incident-state' || typeof state.registryId !== 'string' || typeof state.producerId !== 'string') throw new Error('Invalid incident state')
+  policy(state.policy)
+  readOperationalTime(state.lastObservedAt)
+  if (!/^[a-f0-9]{64}$/.test(state.lastReportId) || !Array.isArray(state.events) || state.events.length > state.policy.maxEvents) throw new Error('Invalid incident cursor/history')
+  for (const field of ['active', 'pending']) if (!state[field] || typeof state[field] !== 'object' || Array.isArray(state[field]) || Object.keys(state[field]).length > 4096) throw new Error('Invalid incident index')
+  if (!Number.isSafeInteger(state.prunedEvents) || state.prunedEvents < 0) throw new Error('Invalid retention counter')
+  for (const event of state.events) {
+    if (!/^[a-f0-9]{64}$/.test(event.id) || !/^[a-f0-9]{64}$/.test(event.incidentId) || !['opened', 'updated', 'recovered'].includes(event.transition)) throw new Error('Invalid incident event')
+    readOperationalTime(event.at)
+  }
+  if (new Set(state.events.map(e => e.id)).size !== state.events.length) throw new Error('Duplicate incident event')
+  return state
+}
+/** Reads the last atomically committed state; corruption never initializes a new history. */
+export async function readIncidentStore(root) {
+  const wrapper = JSON.parse(await readOperationalFile(join(root, 'state.json'), MAX_BYTES))
+  if (wrapper.sha256 !== hash(canonical(wrapper.state))) throw new Error('Incident state checksum mismatch')
+  return validateState(wrapper.state)
+}
+function conditions(report, registry) {
+  const entries = [], add = (feedId, stageId, disposition, state, reasons) => {
+    entries.push({ key: JSON.stringify([report.producerId, feedId, stageId]), feedId, stageId, disposition, state, reasons: [...reasons].sort() })
+  }
+  const available = report.telemetry.state === 'current'
+  add(null, 'telemetry', available ? 'healthy' : 'problem', available ? 'healthy' : 'unknown', available ? [] : [`telemetry-${report.telemetry.state}`])
+  add(null, 'capacity', !available ? 'hold' : report.capacity.state === 'healthy' ? 'healthy' : 'problem', report.capacity.state, report.capacity.reasons)
+  for (const feed of report.feeds) {
+    const definition = registry.feeds.find(f => f.id === feed.feedId)
+    const actionable = stage => stage.state === 'degraded' || stage.state === 'unknown' && !stage.reasons.some(r => notInstrumented.has(r))
+    const blocked = id => definition.stages.find(s => s.id === id).dependsOn.some(parent => actionable(feed.stages.find(s => s.stageId === parent)) || blocked(parent))
+    for (const stage of feed.stages) {
+      let disposition = !available || feed.configuredState !== 'active' ? 'hold' : stage.state === 'healthy' ? 'healthy' : actionable(stage) ? 'problem' : 'hold'
+      if (disposition === 'problem' && (blocked(stage.stageId) || stage.reasons.includes('host-storage-blocked'))) disposition = 'hold'
+      add(feed.feedId, stage.stageId, disposition, stage.state, stage.reasons)
+    }
+  }
+  return entries
+}
+function advance(previous, report, registry, p) {
+  const at = report.observedAt, now = Date.parse(at), reportId = hash(canonical(report))
+  if (previous) {
+    if (previous.registryId !== registry.id || previous.producerId !== report.producerId || canonical(previous.policy) !== canonical(p)) throw new Error('Store identity/policy mismatch')
+    const order = now - Date.parse(previous.lastObservedAt)
+    if (order < 0 || order === 0 && previous.lastReportId !== reportId) throw new Error('Out-of-order or conflicting observation')
+    if (order === 0) return { state: previous, changed: false, events: [] }
+  }
+  const state = previous ? structuredClone(previous) : { schemaVersion: 1, kind: 'feed-incident-state', registryId: registry.id, producerId: report.producerId, policy: p, active: {}, pending: {}, events: [], prunedEvents: 0 }
+  const transitions = []
+  const emit = (incident, transition, health, reasons) => {
+    const event = { incidentId: incident.incidentId, key: incident.key, feedId: incident.feedId, stageId: incident.stageId, firstDetectedAt: incident.firstDetectedAt, at, transition, state: health, reasons }
+    transitions.push({ id: hash(canonical(event)), ...event })
+  }
+  const observedKeys = new Set()
+  for (const condition of conditions(report, registry)) {
+    const { key, disposition, state: health, reasons, feedId, stageId } = condition
+    observedKeys.add(key)
+    let incident = state.active[key]
+    if (disposition === 'problem') {
+      if (!incident) {
+        const candidate = state.pending[key] ?? { since: at }
+        state.pending[key] = candidate
+        if (now - Date.parse(candidate.since) < p.openAfterSeconds * 1000) continue
+        incident = { key, feedId, stageId, incidentId: hash(canonical([key, candidate.since])), firstDetectedAt: candidate.since, openedAt: at, lastObservedAt: at, state: health, reasons }
+        state.active[key] = incident; delete state.pending[key]
+        emit(incident, 'opened', health, reasons)
+      } else {
+        if (incident.state !== health || canonical(incident.reasons) !== canonical(reasons)) emit(incident, 'updated', health, reasons)
+        incident.state = health; incident.reasons = reasons; incident.lastObservedAt = at
+      }
+      delete incident.recoveryStartedAt; delete incident.recoveryProducerAt
+    } else {
+      delete state.pending[key]
+      if (!incident) continue
+      if (disposition === 'hold') { delete incident.recoveryStartedAt; delete incident.recoveryProducerAt; continue }
+      incident.recoveryStartedAt ??= at
+      incident.recoveryProducerAt ??= report.producerGeneratedAt
+      // Fresh observer timestamps alone cannot make a replayed producer report confirm recovery.
+      const fresh = p.recoverAfterSeconds === 0 || Date.parse(report.producerGeneratedAt) > Date.parse(incident.recoveryProducerAt)
+      if (fresh && now - Date.parse(incident.recoveryStartedAt) >= p.recoverAfterSeconds * 1000) {
+        emit(incident, 'recovered', 'healthy', reasons)
+        delete state.active[key]
+      }
+    }
+  }
+  // Removed/paused scopes cannot silently recover existing incidents.
+  for (const key of Object.keys(state.pending)) if (!observedKeys.has(key)) delete state.pending[key]
+  for (const [key, incident] of Object.entries(state.active)) if (!observedKeys.has(key)) { delete incident.recoveryStartedAt; delete incident.recoveryProducerAt }
+  state.events.push(...transitions)
+  const cutoff = now - p.retentionDays * 86400000
+  const expired = new Set(state.events.filter(e => e.transition === 'recovered' && Date.parse(e.at) < cutoff).map(e => e.incidentId))
+  for (const incident of Object.values(state.active)) expired.delete(incident.incidentId)
+  const before = state.events.length
+  state.events = state.events.filter(e => !expired.has(e.incidentId))
+  state.prunedEvents += before - state.events.length
+  state.lastObservedAt = at; state.lastReportId = reportId; state.report = report
+  if (state.events.length > p.maxEvents) throw new Error('Incident history event budget exhausted; archive before continuing')
+  return { state: validateState(state), changed: true, events: transitions }
+}
+
+/** Single-writer transaction: checksum + fsync + atomic rename. A leftover lock fails closed. */
+export async function updateIncidentStore(root, registryValue, reportValue, { policy: requestedPolicy, now = Date.now() } = {}) {
+  const registry = readFeedRegistry(registryValue), report = readFeedHealth(reportValue, registry), p = policy(requestedPolicy)
+  if (!Number.isFinite(now) || now - Date.parse(report.observedAt) > registry.heartbeatMaxAgeSeconds * 1000 || Date.parse(report.observedAt) - now > registry.clockSkewSeconds * 1000) throw new Error('Incident observation is not current')
+  root = resolve(root)
+  // Serialize directory creation as well as updates: a second initializer must not
+  // take the writer lock before the directory creator has committed its first state.
+  const lockPath = `${root}.lock`, lock = await open(lockPath, 'wx', 0o600)
+  const temporary = join(root, `.state-${randomUUID()}`)
+  try {
+    await lock.writeFile(JSON.stringify({ pid: process.pid, host: hostname(), startedAt: new Date(now).toISOString() }))
+    await lock.sync()
+    let created = false
+    try { await mkdir(root, { mode: 0o700 }); created = true } catch (error) { if (error.code !== 'EEXIST') throw error }
+    if (!(await lstat(root)).isDirectory()) throw new Error('Incident store must be a real directory')
+    const previous = created ? null : await readIncidentStore(root)
+    const update = advance(previous, report, registry, p)
+    if (!update.changed) return update
+    const content = canonical({ sha256: hash(canonical(update.state)), state: update.state }) + '\n'
+    if (Buffer.byteLength(content) > MAX_BYTES) throw new Error('Incident history byte budget exhausted; archive before continuing')
+    const output = await open(temporary, 'wx', 0o600)
+    try { await output.writeFile(content); await output.sync() } finally { await output.close() }
+    await rename(temporary, join(root, 'state.json'))
+    const directory = await open(root, 'r')
+    try { await directory.sync() } finally { await directory.close() }
+    return update
+  } finally {
+    await lock.close()
+    try { await rm(temporary, { force: true }) } finally { await rm(lockPath) }
+  }
+}

package/feed-observability.d.mts

@@ -0,0 +1,68 @@
+export type OperationalState = 'healthy' | 'degraded' | 'unknown' | 'waiting'
+export type ConfiguredState = 'active' | 'paused' | 'setup-required'
+export type FeedSchedule = { kind: 'interval'; seconds: number } | { kind: 'daily'; timeZone: string; deadline: string } | { kind: 'manual' | 'push' }
+export interface FeedStage {
+  id: string
+  dependsOn: string[]
+  maxAgeSeconds: number | null
+  sourceMaxAgeSeconds?: number
+}
+export interface FeedDefinition {
+  id: string
+  label: string
+  producerId: string
+  producerFeed: string
+  sourceId: string
+  owner: string
+  runbook: string
+  state: ConfiguredState
+  schedule: FeedSchedule
+  stages: FeedStage[]
+}
+export interface FeedRegistry {
+  schemaVersion: 1
+  kind: 'feed-registry'
+  id: string
+  heartbeatMaxAgeSeconds: number
+  clockSkewSeconds: number
+  feeds: FeedDefinition[]
+}
+export interface FeedEvent {
+  schemaVersion: 1
+  kind: 'feed-event'
+  eventId: string
+  feedId: string
+  stageId: string
+  runId: string
+  parentRunId?: string
+  producerId: string
+  revision: string
+  occurredAt: string
+  recordedAt: string
+  type: 'started' | 'succeeded' | 'failed' | 'heartbeat'
+  reasons: string[]
+  metrics: Record<string, number>
+}
+export interface StageHealth {
+  stageId: string
+  state: OperationalState
+  reasons: string[]
+  timestamps: Partial<Record<'receivedAt' | 'sourceGeneratedAt' | 'latestPeriodEnd' | 'lastSuccessAt' | 'lastAttemptAt', string>>
+  metrics: Record<string, number>
+}
+export interface FeedHealth {
+  schemaVersion: 1
+  kind: 'feed-health'
+  registryId: string
+  producerId: string
+  observedAt: string
+  producerGeneratedAt: string | null
+  telemetry: { state: 'current' | 'stale' | 'missing' | 'invalid'; ageSeconds: number | null }
+  feeds: { feedId: string; configuredState: ConfiguredState; state: OperationalState | Exclude<ConfiguredState, 'active'>; stages: StageHealth[] }[]
+  capacity: { state: Exclude<OperationalState, 'waiting'>; reasons: string[]; metrics: Record<string, number> }
+}
+export function readOperationalTime(value: unknown): string
+export function readFeedRegistry(value: unknown): FeedRegistry
+export function readFeedEvent(value: unknown, registry: unknown): FeedEvent
+export function readFeedHealth(value: unknown, registry: unknown): FeedHealth
+export function summarizeFeedStages(stages: readonly Pick<StageHealth, 'state'>[]): OperationalState

package/feed-observability.mjs

@@ -0,0 +1,154 @@
+/** Versioned, JSON-only contracts. No I/O, clock, Node imports or provider calls. */
+const own = (o, k) => Object.hasOwn(o, k)
+function object(value, keys, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`Invalid ${label}`)
+  if (Object.keys(value).some(k => !keys.includes(k))) throw new Error(`Unknown ${label} field`)
+  return value
+}
+function text(value, label, limit = 160) {
+  if (typeof value !== 'string' || !value.trim() || value.length > limit || [...value].some(c => c.charCodeAt(0) < 32)) throw new Error(`Invalid ${label}`)
+  return value
+}
+function id(value) {
+  if (typeof value !== 'string' || !/^[a-z0-9][a-z0-9._:-]{0,127}$/.test(value)) throw new Error('Invalid identifier')
+  return value
+}
+function choice(value, values) {
+  if (!values.includes(value)) throw new Error('Invalid enum value')
+  return value
+}
+function number(value, max = Number.MAX_SAFE_INTEGER) {
+  if (!Number.isFinite(value) || value < 0 || value > max) throw new Error('Invalid nonnegative number')
+  return value
+}
+function seconds(value) {
+  if (!Number.isInteger(value) || value < 1 || value > 366 * 86400) throw new Error('Invalid duration')
+  return value
+}
+function array(value, max, min = 0) {
+  if (!Array.isArray(value) || value.length < min || value.length > max) throw new Error('Invalid bounded array')
+  return value
+}
+function unique(values) {
+  if (new Set(values).size !== values.length) throw new Error('Duplicate identifier')
+  return values
+}
+export function readOperationalTime(value) {
+  if (typeof value !== 'string' || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{3})?Z$/.test(value)) throw new Error('Invalid UTC timestamp')
+  const ms = Date.parse(value)
+  if (!Number.isFinite(ms) || new Date(ms).toISOString() !== (value.length === 20 ? value.replace('Z', '.000Z') : value)) throw new Error('Invalid UTC timestamp')
+  return new Date(ms).toISOString()
+}
+function header(value, kind, keys) {
+  object(value, ['schemaVersion', 'kind', ...keys], kind)
+  if (value.schemaVersion !== 1 || value.kind !== kind) throw new Error('Unsupported operational schema')
+}
+function schedule(value) {
+  object(value, ['kind', 'seconds', 'timeZone', 'deadline'], 'schedule')
+  if (value.kind === 'interval') {
+    object(value, ['kind', 'seconds'], 'interval schedule')
+    return { kind: value.kind, seconds: seconds(value.seconds) }
+  }
+  if (value.kind === 'daily') {
+    object(value, ['kind', 'timeZone', 'deadline'], 'daily schedule')
+    text(value.timeZone, 'timezone', 80)
+    new Intl.DateTimeFormat('en', { timeZone: value.timeZone })
+    if (!/^(?:[01]\d|2[0-3]):[0-5]\d$/.test(value.deadline)) throw new Error('Invalid daily deadline')
+    return { kind: value.kind, timeZone: value.timeZone, deadline: value.deadline }
+  }
+  object(value, ['kind'], 'manual schedule')
+  return { kind: choice(value.kind, ['manual', 'push']) }
+}
+export function readFeedRegistry(value) {
+  header(value, 'feed-registry', ['id', 'heartbeatMaxAgeSeconds', 'clockSkewSeconds', 'feeds'])
+  const feeds = array(value.feeds, 128, 1).map(f => {
+    object(f, ['id', 'label', 'producerId', 'producerFeed', 'sourceId', 'owner', 'runbook', 'state', 'schedule', 'stages'], 'feed')
+    const stages = array(f.stages, 16, 1).map(s => {
+      object(s, ['id', 'dependsOn', 'maxAgeSeconds', 'sourceMaxAgeSeconds'], 'stage')
+      return { id: id(s.id), dependsOn: unique(array(s.dependsOn, 16).map(id)),
+        maxAgeSeconds: s.maxAgeSeconds === null ? null : seconds(s.maxAgeSeconds),
+        ...(own(s, 'sourceMaxAgeSeconds') ? { sourceMaxAgeSeconds: seconds(s.sourceMaxAgeSeconds) } : {}) }
+    })
+    unique(stages.map(s => s.id))
+    const visiting = new Set(), visited = new Set()
+    const visit = stageId => {
+      if (visiting.has(stageId)) throw new Error('Cyclic stage dependency')
+      if (visited.has(stageId)) return
+      const stage = stages.find(s => s.id === stageId)
+      if (!stage) throw new Error('Unknown stage dependency')
+      visiting.add(stageId); stage.dependsOn.forEach(visit); visiting.delete(stageId); visited.add(stageId)
+    }
+    stages.forEach(s => visit(s.id))
+    return { id: id(f.id), label: text(f.label, 'label'), producerId: id(f.producerId), producerFeed: id(f.producerFeed), sourceId: id(f.sourceId),
+      owner: text(f.owner, 'owner'), runbook: text(f.runbook, 'runbook', 300), state: choice(f.state, ['active', 'paused', 'setup-required']), schedule: schedule(f.schedule), stages }
+  })
+  unique(feeds.map(f => f.id)); unique(feeds.map(f => `${f.producerId}/${f.producerFeed}`))
+  return { schemaVersion: 1, kind: 'feed-registry', id: id(value.id), heartbeatMaxAgeSeconds: seconds(value.heartbeatMaxAgeSeconds),
+    clockSkewSeconds: number(value.clockSkewSeconds, 300), feeds }
+}
+function metrics(value) {
+  object(value, Object.keys(value ?? {}), 'metrics')
+  if (Object.keys(value).length > 32) throw new Error('Too many metrics')
+  return Object.fromEntries(Object.entries(value).map(([key, v]) => [id(key), number(v)]))
+}
+function reasons(value) { return unique(array(value, 16).map(id)) }
+function registered(registry, feedId, stageId) {
+  const feed = registry.feeds.find(f => f.id === feedId)
+  if (!feed?.stages.some(s => s.id === stageId)) throw new Error('Unregistered feed or stage')
+}
+export function readFeedEvent(value, registryValue) {
+  header(value, 'feed-event', ['eventId', 'feedId', 'stageId', 'runId', 'parentRunId', 'producerId', 'revision', 'occurredAt', 'recordedAt', 'type', 'reasons', 'metrics'])
+  const registry = readFeedRegistry(registryValue)
+  registered(registry, value.feedId, value.stageId)
+  if (registry.feeds.find(f => f.id === value.feedId).producerId !== value.producerId) throw new Error('Producer does not own feed')
+  return { schemaVersion: 1, kind: 'feed-event', eventId: id(value.eventId), feedId: id(value.feedId), stageId: id(value.stageId), runId: id(value.runId),
+    ...(own(value, 'parentRunId') ? { parentRunId: id(value.parentRunId) } : {}), producerId: id(value.producerId), revision: id(value.revision),
+    occurredAt: readOperationalTime(value.occurredAt), recordedAt: readOperationalTime(value.recordedAt),
+    type: choice(value.type, ['started', 'succeeded', 'failed', 'heartbeat']), reasons: reasons(value.reasons), metrics: metrics(value.metrics) }
+}
+export function summarizeFeedStages(stages) {
+  return ['degraded', 'unknown', 'waiting'].find(state => stages.some(s => s.state === state)) ?? 'healthy'
+}
+export function readFeedHealth(value, registryValue) {
+  header(value, 'feed-health', ['registryId', 'producerId', 'observedAt', 'producerGeneratedAt', 'telemetry', 'feeds', 'capacity'])
+  const registry = readFeedRegistry(registryValue)
+  if (value.registryId !== registry.id) throw new Error('Registry does not match health report')
+  const producerId = id(value.producerId), expected = registry.feeds.filter(f => f.producerId === producerId)
+  if (!expected.length) throw new Error('Unregistered producer')
+  const observedAt = readOperationalTime(value.observedAt)
+  const producerGeneratedAt = value.producerGeneratedAt === null ? null : readOperationalTime(value.producerGeneratedAt)
+  object(value.telemetry, ['state', 'ageSeconds'], 'telemetry')
+  const telemetry = { state: choice(value.telemetry.state, ['current', 'stale', 'missing', 'invalid']), ageSeconds: value.telemetry.ageSeconds === null ? null : number(value.telemetry.ageSeconds) }
+  if (producerGeneratedAt === null) {
+    if (!['missing', 'invalid'].includes(telemetry.state) || telemetry.ageSeconds !== null) throw new Error('Missing producer clock cannot establish freshness')
+  } else {
+    const elapsed = (Date.parse(observedAt) - Date.parse(producerGeneratedAt)) / 1000
+    const state = elapsed < -registry.clockSkewSeconds ? 'invalid' : elapsed > registry.heartbeatMaxAgeSeconds ? 'stale' : 'current'
+    if (telemetry.state !== state || telemetry.ageSeconds === null || Math.abs(telemetry.ageSeconds - Math.max(0, elapsed)) > 0.000001) throw new Error('Telemetry does not match report clocks')
+  }
+  const feeds = array(value.feeds, 128, 1).map(f => {
+    object(f, ['feedId', 'configuredState', 'state', 'stages'], 'feed health')
+    const entry = expected.find(e => e.id === f.feedId)
+    if (!entry || f.configuredState !== entry.state) throw new Error('Feed configuration does not match registry')
+    const stages = array(f.stages, 16, 1).map(s => {
+      object(s, ['stageId', 'state', 'reasons', 'timestamps', 'metrics'], 'stage health')
+      registered(registry, f.feedId, s.stageId)
+      object(s.timestamps, ['receivedAt', 'sourceGeneratedAt', 'latestPeriodEnd', 'lastSuccessAt', 'lastAttemptAt'], 'timestamps')
+      return { stageId: id(s.stageId), state: choice(s.state, ['healthy', 'degraded', 'unknown', 'waiting']), reasons: reasons(s.reasons),
+        timestamps: Object.fromEntries(Object.entries(s.timestamps).map(([k, v]) => [k, readOperationalTime(v)])), metrics: metrics(s.metrics) }
+    })
+    unique(stages.map(s => s.stageId))
+    if (stages.length !== entry.stages.length) throw new Error('Incomplete stage report')
+    const state = entry.state === 'active' ? summarizeFeedStages(stages) : entry.state
+    if (f.state !== state) throw new Error('Inconsistent feed summary')
+    if (telemetry.state !== 'current' && stages.some(s => s.state !== 'unknown')) throw new Error('Unavailable telemetry cannot assert stage health')
+    return { feedId: f.feedId, configuredState: entry.state, state, stages }
+  })
+  unique(feeds.map(f => f.feedId))
+  if (feeds.length !== expected.length) throw new Error('Incomplete producer report')
+  object(value.capacity, ['state', 'reasons', 'metrics'], 'capacity')
+  const capacity = { state: choice(value.capacity.state, ['healthy', 'degraded', 'unknown']), reasons: reasons(value.capacity.reasons), metrics: metrics(value.capacity.metrics) }
+  if (telemetry.state !== 'current' && capacity.state !== 'unknown') throw new Error('Unavailable telemetry cannot assert capacity health')
+  return { schemaVersion: 1, kind: 'feed-health', registryId: registry.id, producerId, observedAt,
+    producerGeneratedAt, telemetry, feeds, capacity }
+}

package/feed-observer.d.mts

@@ -0,0 +1,30 @@
+import type { SERVICE_TIMEZONE } from './uk-service-day.mjs'
+import type { FeedHealth, StageHealth } from './feed-observability.mjs'
+import type { DailyExpectation } from './feed-expectations.mjs'
+export type ObserverCredential = string | { bearer?: string; accessClientId?: string; accessClientSecret?: string }
+export interface ObserverConfig {
+  schemaVersion: 1
+  kind: 'feed-observer-config'
+  producerId: string
+  healthUrl: string
+  consumers: { feedId: string; manifestUrl: string; operator: string; deadline: string; timeZone: typeof SERVICE_TIMEZONE }[]
+}
+export interface ObserverCheck {
+  schemaVersion: 1
+  kind: 'feed-observer-check'
+  startedAt: string
+  completedAt: string
+  sourceError: string | null
+  requests: number
+  bytes: number
+  report: FeedHealth
+  consumers: (StageHealth & { feedId: string; expectation: DailyExpectation })[]
+}
+export declare const OBSERVER_LIMITS: Readonly<{ requests: number; totalBytes: number; timeoutMs: number; totalMs: number; healthBytes: number; manifestBytes: number; releaseBytes: number }>
+export function observeFeeds(registry: unknown, config: unknown, options?: {
+  fetchImpl?: typeof fetch
+  clock?: () => number
+  tokens?: { health?: ObserverCredential; consumers?: Record<string, ObserverCredential> }
+  limits?: typeof OBSERVER_LIMITS
+}): Promise<ObserverCheck>
+export function assessObserverCheck(registry: unknown, checked: ObserverCheck | null | undefined, options?: { now?: number; maxAgeSeconds?: number }): { state: 'healthy' | 'degraded' | 'unknown'; reasons: string[] }

package/feed-observer.mjs

@@ -0,0 +1,192 @@
+import { readFeedRegistry, readFeedHealth, readOperationalTime, summarizeFeedStages } from './feed-observability.mjs'
+import { recorderFeedHealth } from './recorder-observability.mjs'
+import { dailyFeedExpectation } from './feed-expectations.mjs'
+import { studyDay, SERVICE_TIMEZONE } from './uk-service-day.mjs'
+
+export const OBSERVER_LIMITS = Object.freeze({ requests: 9, totalBytes: 10 * 1024 * 1024, timeoutMs: 5000, totalMs: 30000, healthBytes: 1024 * 1024, manifestBytes: 8192, releaseBytes: 2 * 1024 * 1024 })
+const digest = s => typeof s === 'string' && /^[a-f0-9]{64}$/.test(s)
+const sha = async bytes => [...new Uint8Array(await crypto.subtle.digest('SHA-256', bytes))].map(b => b.toString(16).padStart(2, '0')).join('')
+const stage = (state, reason, timestamps = {}, metrics = {}) => ({ stageId: 'serve', state, reasons: [reason], timestamps, metrics })
+function checkUrl(value) {
+  const url = new URL(value)
+  if (url.username || url.password || url.hash || url.search || !['https:', 'http:'].includes(url.protocol) || url.protocol === 'http:' && !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) throw new Error('Use HTTPS or loopback HTTP without embedded credentials or query strings')
+  return url.href
+}
+function config(value, registry) {
+  if (value?.schemaVersion !== 1 || value.kind !== 'feed-observer-config' || Object.keys(value).some(k => !['schemaVersion', 'kind', 'producerId', 'healthUrl', 'consumers'].includes(k))) throw new Error('Invalid observer config')
+  if (!registry.feeds.some(f => f.producerId === value.producerId) || !Array.isArray(value.consumers) || value.consumers.length > 4) throw new Error('Invalid observer targets')
+  const consumers = value.consumers.map(c => {
+    if (!c || Object.keys(c).some(k => !['feedId', 'manifestUrl', 'operator', 'deadline', 'timeZone'].includes(k))) throw new Error('Invalid consumer config')
+    if (!registry.feeds.some(f => f.id === c.feedId && f.producerId === value.producerId && f.stages.some(s => s.id === 'serve'))) throw new Error('Register the consumer serve stage')
+    if (typeof c.operator !== 'string' || !c.operator.trim() || c.operator.length > 100 || c.timeZone !== SERVICE_TIMEZONE || !/^(?:[01]\d|2[0-3]):[0-5]\d$/.test(c.deadline)) throw new Error('Invalid bus consumer expectation')
+    return { ...c, manifestUrl: checkUrl(c.manifestUrl) }
+  })
+  if (new Set(consumers.map(c => c.feedId)).size !== consumers.length) throw new Error('Duplicate consumer target')
+  return { producerId: value.producerId, healthUrl: checkUrl(value.healthUrl), consumers }
+}
+class CheckError extends Error { constructor(reason) { super(reason); this.reason = reason } }
+function client(fetchImpl, tokens, limits) {
+  const began = performance.now(), usage = { requests: 0, bytes: 0 }
+  const read = async (url, cap, token) => {
+    if (usage.requests >= limits.requests || usage.bytes >= limits.totalBytes || performance.now() - began >= limits.totalMs) throw new CheckError('check-budget-exhausted')
+    usage.requests++
+    const controller = new AbortController()
+    let reader, body, timer
+    const timeout = new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(); reject(new CheckError('request-timeout')) }, Math.min(limits.timeoutMs, limits.totalMs - (performance.now() - began))) })
+    try {
+      return await Promise.race([timeout, (async () => {
+        const credential = typeof token === 'string' ? { bearer: token } : token ?? {}
+        const headers = { Accept: 'application/json', 'Cache-Control': 'no-cache', ...(credential.bearer ? { Authorization: `Bearer ${credential.bearer}` } : {}) }
+        if (credential.accessClientId && credential.accessClientSecret) {
+          headers['CF-Access-Client-Id'] = credential.accessClientId
+          headers['CF-Access-Client-Secret'] = credential.accessClientSecret
+        } else if (credential.accessClientId || credential.accessClientSecret) throw new CheckError('credentials-invalid')
+        const response = await fetchImpl(url, { headers, signal: controller.signal, redirect: 'error', cache: 'no-store' })
+        body = response.body
+        if (!response.ok || response.redirected) throw new CheckError('http-unavailable')
+        const advertised = response.headers.get('content-length')
+        if (advertised !== null && (!/^\d+$/.test(advertised) || Number(advertised) > cap)) throw new CheckError('response-too-large')
+        reader = response.body?.getReader()
+        if (!reader) throw new CheckError('document-invalid')
+        let size = 0
+        const chunks = []
+        while (true) {
+          const { done, value } = await reader.read()
+          if (done) break
+          size += value.byteLength; usage.bytes += value.byteLength
+          if (size > cap || usage.bytes > limits.totalBytes) throw new CheckError('response-too-large')
+          chunks.push(value)
+        }
+        const bytes = new Uint8Array(size)
+        let offset = 0
+        for (const c of chunks) { bytes.set(c, offset); offset += c.length }
+        let json
+        try { json = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)) } catch { throw new CheckError('document-invalid') }
+        return { bytes, json }
+      })()])
+    } catch (e) { throw e instanceof CheckError ? e : new CheckError('request-failed') }
+    finally { clearTimeout(timer); controller.abort(); if (reader) void reader.cancel().catch(() => {}); else if (body) void body.cancel().catch(() => {}) }
+  }
+  return { usage, health: url => read(url, limits.healthBytes, tokens.health), consumer: (url, kind, token) => read(url, limits[`${kind}Bytes`], token) }
+}
+
+/** Reevaluate a mirrored producer report at the checker's clock; never renew its heartbeat. */
+function refresh(registry, raw, producerId, now) {
+  const report = readFeedHealth(raw, registry)
+  if (report.producerId !== producerId || Date.parse(report.observedAt) > now + registry.clockSkewSeconds * 1000) throw new Error('Unexpected producer/observer clock')
+  const generated = report.producerGeneratedAt ? Date.parse(report.producerGeneratedAt) : null
+  const elapsed = generated === null ? null : (now - generated) / 1000
+  report.observedAt = new Date(now).toISOString()
+  report.telemetry = { state: elapsed === null ? report.telemetry.state : elapsed < -registry.clockSkewSeconds ? 'invalid' : elapsed > registry.heartbeatMaxAgeSeconds ? 'stale' : 'current', ageSeconds: elapsed === null ? null : Math.max(0, elapsed) }
+  for (const f of report.feeds) {
+    const entry = registry.feeds.find(e => e.id === f.feedId)
+    f.stages = f.stages.map(s => {
+      if (report.telemetry.state !== 'current') return { ...s, state: 'unknown', reasons: [`telemetry-${report.telemetry.state}`], timestamps: {}, metrics: {} }
+      const def = entry.stages.find(d => d.id === s.stageId)
+      const field = { capture: 'receivedAt', normalize: 'latestPeriodEnd', analytics: 'lastAttemptAt' }[s.stageId]
+      const metric = { capture: 'capture-age-seconds', normalize: 'normalization-lag-seconds', analytics: 'analytics-status-age-seconds' }[s.stageId]
+      if (field && s.timestamps[field]) s.metrics[metric] = Math.max(0, (now - Date.parse(s.timestamps[field])) / 1000)
+      if (s.stageId === 'capture' && s.timestamps.sourceGeneratedAt) s.metrics['source-age-seconds'] = Math.max(0, (now - Date.parse(s.timestamps.sourceGeneratedAt)) / 1000)
+      if (f.configuredState !== 'active' || !['healthy', 'waiting'].includes(s.state)) return s
+      if (field && def.maxAgeSeconds !== null) {
+        const stamp = s.timestamps[field], age = stamp ? (now - Date.parse(stamp)) / 1000 : null
+        if (age === null) return { ...s, state: 'unknown', reasons: ['stage-clock-unavailable'] }
+        if (age < -registry.clockSkewSeconds) return { ...s, state: 'unknown', reasons: ['stage-clock-invalid'] }
+        if (age > def.maxAgeSeconds) return { ...s, state: s.stageId === 'analytics' ? 'unknown' : 'degraded', reasons: [`${s.stageId}-stale`] }
+      }
+      if (s.stageId === 'capture' && def.sourceMaxAgeSeconds) {
+        const stamp = s.timestamps.sourceGeneratedAt
+        if (!stamp) return { ...s, state: 'unknown', reasons: ['source-time-unavailable'] }
+        if ((now - Date.parse(stamp)) / 1000 < -registry.clockSkewSeconds) return { ...s, state: 'unknown', reasons: ['source-clock-invalid'] }
+        if ((now - Date.parse(stamp)) / 1000 > def.sourceMaxAgeSeconds) return { ...s, state: 'degraded', reasons: ['source-stale'] }
+      }
+      return s
+    })
+    f.state = f.configuredState === 'active' ? summarizeFeedStages(f.stages) : f.configuredState
+  }
+  if (report.telemetry.state !== 'current') report.capacity = { state: 'unknown', reasons: [`telemetry-${report.telemetry.state}`], metrics: {} }
+  return readFeedHealth(report, registry)
+}
+
+async function consumer(c, expectation, api, now, skew, token) {
+  try {
+    const { json: manifest } = await api.consumer(c.manifestUrl, 'manifest', token)
+    const id = manifest.resultId, file = manifest.report
+    if (manifest.schemaVersion !== 1 || !digest(id) || file?.path !== `releases/${id}/result.json` || !Number.isSafeInteger(file.bytes) || file.bytes < 1 || file.bytes > OBSERVER_LIMITS.releaseBytes || !digest(file.sha256)) throw new CheckError('manifest-invalid')
+    const publishedAt = readOperationalTime(manifest.observedAt)
+    if (Date.parse(publishedAt) > now + skew * 1000) throw new CheckError('publication-clock-invalid')
+    const { json: release, bytes } = await api.consumer(new URL(file.path, c.manifestUrl).href, 'release', token)
+    const { resultId, ...payload } = release
+    if (bytes.length !== file.bytes || await sha(bytes) !== file.sha256 || resultId !== id || await sha(new TextEncoder().encode(JSON.stringify(payload))) !== id) throw new CheckError('release-integrity-failed')
+    if (release.schemaVersion !== 2 || release.kind !== 'feed-quality-history' || release.operator !== c.operator || !Array.isArray(release.days) || release.days.length > 366) throw new CheckError('release-invalid')
+    readOperationalTime(`${release.from}T00:00:00Z`); readOperationalTime(`${release.to}T00:00:00Z`)
+    if (release.from > release.to) throw new CheckError('release-invalid')
+    const expected = studyDay(expectation.serviceDate)
+    const selected = release.days.filter(d => d.date === expectation.serviceDate)
+    if (release.from > expectation.serviceDate || release.to < expectation.serviceDate || selected.length === 0) return stage('degraded', 'consumer-period-overdue')
+    if (selected.length !== 1) throw new CheckError('release-invalid')
+    const day = selected[0]
+    if (day.status !== 'current') return stage('degraded', 'consumer-day-overdue')
+    if (!digest(day.revision) || !day.quality || day.day?.startUtc !== expected.startUtc || day.day?.endUtc !== expected.endUtc || day.day?.serviceDate !== expected.serviceDate || Date.parse(publishedAt) < Date.parse(expected.endUtc)) throw new CheckError('release-day-invalid')
+    return stage('healthy', 'consumer-release-verified', { lastSuccessAt: publishedAt, latestPeriodEnd: expected.endUtc }, { 'verified-release-bytes': bytes.length })
+  } catch (e) { return stage('degraded', `consumer-${e instanceof CheckError ? e.reason : 'document-invalid'}`) }
+}
+
+/** Portable Web-API checker; reads configured endpoints only, with no redirects or retries. */
+export async function observeFeeds(registryValue, configValue, { fetchImpl = fetch, clock = Date.now, tokens = {}, limits = OBSERVER_LIMITS } = {}) {
+  const registry = readFeedRegistry(registryValue), c = config(configValue, registry)
+  // Tests may lower bounds, never raise them.
+  for (const [key, value] of Object.entries(OBSERVER_LIMITS)) if (!Number.isSafeInteger(limits[key]) || limits[key] < 1 || limits[key] > value) throw new Error('Invalid check limit')
+  const api = client(fetchImpl, tokens, limits), startedAt = new Date(clock()).toISOString()
+  let source = null, sourceError = null
+  try { source = (await api.health(c.healthUrl)).json; refresh(registry, source, c.producerId, clock()) }
+  catch (e) { source = null; sourceError = e instanceof CheckError ? e.reason : 'document-invalid' }
+  const checks = []
+  for (const target of c.consumers) {
+    const definition = registry.feeds.find(f => f.id === target.feedId)
+    if (definition.state !== 'active') continue
+    const expectation = dailyFeedExpectation(target, clock())
+    const health = await consumer(target, expectation, api, clock(), registry.clockSkewSeconds, tokens.consumers?.[target.feedId])
+    checks.push({ feedId: target.feedId, expectation, ...health })
+  }
+  const finished = clock()
+  for (const check of checks) {
+    const target = c.consumers.find(t => t.feedId === check.feedId), latest = dailyFeedExpectation(target, finished)
+    if (latest.serviceDate !== check.expectation.serviceDate) Object.assign(check, stage('degraded', 'consumer-expectation-advanced'), { expectation: latest })
+  }
+  let report
+  if (source) report = refresh(registry, source, c.producerId, finished)
+  else report = recorderFeedHealth(registry, sourceError === 'document-invalid' ? {} : null, { producerId: c.producerId, now: finished })
+  if (report.telemetry.state === 'current') for (const check of checks) {
+    const feed = report.feeds.find(f => f.feedId === check.feedId)
+    const { feedId: _feedId, expectation: _expectation, ...health } = check
+    feed.stages = feed.stages.map(s => s.stageId === 'serve' ? health : s)
+    feed.state = summarizeFeedStages(feed.stages)
+  }
+  return { schemaVersion: 1, kind: 'feed-observer-check', startedAt, completedAt: new Date(finished).toISOString(), sourceError, requests: api.usage.requests, bytes: api.usage.bytes,
+    report: readFeedHealth(report, registry), consumers: checks }
+}
+
+/** Assess a stored check at read time. A successful old check is historical evidence. */
+export function assessObserverCheck(registryValue, checked, { now = Date.now(), maxAgeSeconds = 180 } = {}) {
+  const registry = readFeedRegistry(registryValue)
+  if (!Number.isFinite(now) || !Number.isSafeInteger(maxAgeSeconds) || maxAgeSeconds < 1 || maxAgeSeconds > 3600) throw new Error('Invalid observer clock/threshold')
+  const unknown = reason => ({ state: 'unknown', reasons: [reason] })
+  if (!checked) return unknown('checker-missing')
+  try {
+    if (checked.schemaVersion !== 1 || checked.kind !== 'feed-observer-check' || !Array.isArray(checked.consumers)) return unknown('checker-invalid')
+    const completed = Date.parse(readOperationalTime(checked.completedAt)), started = Date.parse(readOperationalTime(checked.startedAt))
+    if (started > completed || completed > now + registry.clockSkewSeconds * 1000) return unknown('checker-clock-invalid')
+    if (now - completed > maxAgeSeconds * 1000) return unknown('checker-stale')
+    const report = refresh(registry, checked.report, checked.report.producerId, now)
+    if (report.telemetry.state !== 'current') return unknown(`telemetry-${report.telemetry.state}`)
+    for (const c of checked.consumers) {
+      if (Date.parse(readOperationalTime(c.expectation.nextDeadlineAt)) <= now) return unknown('consumer-expectation-expired')
+      if (!['healthy', 'degraded', 'unknown', 'waiting'].includes(c.state)) return unknown('checker-invalid')
+    }
+    const states = [report.capacity.state, ...report.feeds.filter(f => f.configuredState === 'active').map(f => f.state), ...checked.consumers.map(c => c.state)]
+    if (states.includes('degraded')) return { state: 'degraded', reasons: ['feed-attention-required'] }
+    if (states.includes('unknown')) return unknown('feed-evidence-unavailable')
+    return { state: 'healthy', reasons: ['check-current'] }
+  } catch { return unknown('checker-invalid') }
+}

package/operational-files.mjs

@@ -0,0 +1,21 @@
+import { open, constants } from 'node:fs/promises'
+
+/** Read a bounded regular file without following a final symlink or blocking on a FIFO. */
+export async function readOperationalFile(path, limit) {
+  const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+  try {
+    const stat = await handle.stat()
+    if (!stat.isFile() || stat.size > limit) throw new Error('Input must be a bounded regular file')
+    // Size the buffer from the file, not the limit, so a generous limit costs nothing for small inputs; one spare byte detects growth.
+    const bytes = Buffer.alloc(Math.min(limit, stat.size) + 1)
+    let size = 0
+    while (size <= limit) {
+      const { bytesRead } = await handle.read(bytes, size, bytes.length - size, null)
+      if (!bytesRead) break
+      size += bytesRead
+    }
+    const after = await handle.stat()
+    if (size > limit || size !== stat.size || after.size !== stat.size || after.mtimeMs !== stat.mtimeMs) throw new Error('Input changed or exceeds read limit')
+    return bytes.subarray(0, size)
+  } finally { await handle.close() }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionstudies/data",
-  "version": "0.1.0-alpha.27",
+  "version": "0.1.0-alpha.29",
   "private": false,
   "type": "module",
   "description": "Offline data preparation primitives for Motion Studies.",
@@ -59,6 +59,14 @@
       "types": "./source-store.d.mts",
       "import": "./source-store.mjs"
     },
+    "./release": {
+      "types": "./release.d.mts",
+      "import": "./release.mjs"
+    },
+    "./release-files": {
+      "types": "./release-files.d.mts",
+      "import": "./release-files.mjs"
+    },
     "./uk-service-day": {
       "types": "./uk-service-day.d.mts",
       "import": "./uk-service-day.mjs"
@@ -86,6 +94,30 @@
     "./rail-geometry": {
       "types": "./rail-geometry.d.mts",
       "import": "./rail-geometry.mjs"
+    },
+    "./feed-observability": {
+      "types": "./feed-observability.d.mts",
+      "import": "./feed-observability.mjs"
+    },
+    "./recorder-observability": {
+      "types": "./recorder-observability.d.mts",
+      "import": "./recorder-observability.mjs"
+    },
+    "./recorder-evidence": {
+      "types": "./recorder-evidence.d.mts",
+      "import": "./recorder-evidence.mjs"
+    },
+    "./feed-incidents": {
+      "types": "./feed-incidents.d.mts",
+      "import": "./feed-incidents.mjs"
+    },
+    "./feed-observer": {
+      "types": "./feed-observer.d.mts",
+      "import": "./feed-observer.mjs"
+    },
+    "./feed-expectations": {
+      "types": "./feed-expectations.d.mts",
+      "import": "./feed-expectations.mjs"
     }
   },
   "files": [
@@ -101,7 +133,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@motionstudies/core": "0.1.0-alpha.27",
+    "@motionstudies/core": "0.1.0-alpha.29",
     "fast-xml-parser": "5.11.1"
   }
 }

package/recorder-evidence.d.mts

@@ -0,0 +1,14 @@
+import type { FeedHealth } from './feed-observability.mjs'
+export interface RecorderEvidencePlan {
+  schemaVersion: 1
+  kind: 'recorder-evidence-plan'
+  producerId: string
+  validUntil: string
+  feeds: {
+    feedId: string
+    archive?: { journalPath: string; closeoutPath: string; expectedEnd: string; deadlineAt: string }
+    publication?: { pointerPath: string; operator: string; expectedThrough: string; deadlineAt: string }
+  }[]
+}
+/** Reads explicitly selected local files, with integrity checks, 256 MiB per journal and a 512 MiB total read budget. */
+export function recorderEvidenceHealth(registry: unknown, report: unknown, plan: unknown): Promise<FeedHealth>

package/recorder-evidence.mjs

@@ -0,0 +1,136 @@
+import { createHash } from 'node:crypto'
+import { isAbsolute, dirname, join } from 'node:path'
+import { readOperationalFile } from './operational-files.mjs'
+import { readFeedRegistry, readFeedHealth, readOperationalTime, summarizeFeedStages } from './feed-observability.mjs'
+import { studyDay } from './uk-service-day.mjs'
+
+const hash = bytes => createHash('sha256').update(bytes).digest('hex')
+const digest = value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value)
+const count = value => Number.isSafeInteger(value) && value >= 0
+function keys(value, allowed) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(k => !allowed.includes(k))) throw new Error('Invalid evidence plan')
+}
+function path(value) { if (typeof value !== 'string' || !isAbsolute(value) || value.length > 4096) throw new Error('Evidence paths must be absolute'); return value }
+function date(value) { readOperationalTime(`${value}T00:00:00Z`); return value }
+function readPlan(value, registry, producerId) {
+  keys(value, ['schemaVersion', 'kind', 'producerId', 'validUntil', 'feeds'])
+  if (value.schemaVersion !== 1 || value.kind !== 'recorder-evidence-plan' || value.producerId !== producerId || !Array.isArray(value.feeds) || value.feeds.length > 16) throw new Error('Invalid evidence plan')
+  const validUntil = readOperationalTime(value.validUntil)
+  const feeds = value.feeds.map(f => {
+    keys(f, ['feedId', 'archive', 'publication'])
+    const entry = registry.feeds.find(e => e.id === f.feedId && e.producerId === producerId)
+    if (!entry) throw new Error('Unregistered evidence feed')
+    const output = { feedId: f.feedId }
+    for (const id of ['archive', 'publication']) if (f[id]) {
+      if (!entry.stages.some(s => s.id === id)) throw new Error('Unregistered evidence stage')
+      if (id === 'archive') {
+        keys(f[id], ['journalPath', 'closeoutPath', 'expectedEnd', 'deadlineAt'])
+        output.archive = { journalPath: path(f[id].journalPath), closeoutPath: path(f[id].closeoutPath), expectedEnd: readOperationalTime(f[id].expectedEnd), deadlineAt: readOperationalTime(f[id].deadlineAt) }
+      } else {
+        keys(f[id], ['pointerPath', 'operator', 'expectedThrough', 'deadlineAt'])
+        if (typeof f[id].operator !== 'string' || !f[id].operator.trim() || f[id].operator.length > 100) throw new Error('Invalid operator')
+        output.publication = { pointerPath: path(f[id].pointerPath), operator: f[id].operator, expectedThrough: date(f[id].expectedThrough), deadlineAt: readOperationalTime(f[id].deadlineAt) }
+      }
+      const end = id === 'archive' ? output.archive.expectedEnd : studyDay(output.publication.expectedThrough).endUtc
+      if (Date.parse(output[id].deadlineAt) < Date.parse(end)) throw new Error('Evidence deadline precedes expected period end')
+      if (Date.parse(output[id].deadlineAt) > Date.parse(validUntil)) throw new Error('Evidence deadline exceeds plan validity')
+    }
+    return output
+  })
+  if (new Set(feeds.map(f => f.feedId)).size !== feeds.length) throw new Error('Duplicate evidence feed')
+  return { feeds, validUntil }
+}
+const result = (stageId, state, reason, timestamps = {}, metrics = {}) => ({ stageId, state, reasons: reason ? [reason] : [], timestamps, metrics })
+const pending = (id, deadline, now, reason) => result(id, now > Date.parse(deadline) ? 'degraded' : 'waiting', `${reason}-${now > Date.parse(deadline) ? 'overdue' : 'pending'}`)
+
+/** Read explicit local evidence targets; never infer paths from a status report or fetch R2. */
+export async function recorderEvidenceHealth(registryValue, reportValue, planValue) {
+  const registry = readFeedRegistry(registryValue), report = readFeedHealth(reportValue, registry)
+  const plan = readPlan(planValue, registry, report.producerId), now = Date.parse(report.observedAt)
+  // A national bus day's journal is about 140 MiB; smaller feeds are a few MiB.
+  let remaining = 512 * 1024 * 1024
+  const read = async (path, limit) => {
+    if (remaining <= 0) throw new Error('Evidence byte budget exceeded')
+    const bytes = await readOperationalFile(path, Math.min(limit, remaining))
+    remaining -= bytes.length
+    return { bytes, json: JSON.parse(bytes) }
+  }
+  for (const f of plan.feeds) {
+    const feed = report.feeds.find(e => e.feedId === f.feedId)
+    if (report.telemetry.state !== 'current' || feed.configuredState !== 'active') continue
+    const entry = registry.feeds.find(e => e.id === f.feedId)
+    for (const stageId of ['archive', 'publication']) {
+      if (!f[stageId]) continue
+      let evidence
+      try {
+        evidence = now > Date.parse(plan.validUntil) ? result(stageId, 'unknown', 'evidence-plan-expired') : stageId === 'archive' ? await archive(f.archive, entry, read, now, registry.clockSkewSeconds) : await publication(f.publication, read, now, registry.clockSkewSeconds)
+      } catch (error) {
+        evidence = error.code === 'ENOENT' ? pending(stageId, f[stageId].deadlineAt, now, `${stageId}-evidence`) : result(stageId, 'unknown', `${stageId}-evidence-invalid`)
+      }
+      feed.stages = feed.stages.map(s => s.stageId === stageId ? evidence : s)
+    }
+    feed.state = summarizeFeedStages(feed.stages)
+  }
+  return readFeedHealth(report, registry)
+}
+
+async function archive(plan, entry, read, now, skew) {
+  const { bytes, json: journal } = await read(plan.journalPath, 256 * 1024 * 1024)
+  if (!journal.id || journal.config?.source !== entry.sourceId || !['complete', 'stopped'].includes(journal.status) || !Array.isArray(journal.attempts)) throw new Error('Invalid closed journal')
+  const end = readOperationalTime(journal.plannedEnd), start = readOperationalTime(journal.startedAt)
+  if (end !== plan.expectedEnd || Date.parse(end) < Date.parse(start) || Date.parse(end) > now || Date.parse(plan.deadlineAt) < Date.parse(end)) throw new Error('Invalid archive period/deadline')
+  const dates = [...new Set(journal.attempts.filter(a => a.status === 'captured').map(a => readOperationalTime(a.receivedAt).slice(0, 10)))].sort()
+  if (!dates.length || dates.length > 7) throw new Error('Archive has no bounded captured dates')
+  const { json: record } = await read(plan.closeoutPath, 1024 * 1024)
+  if (record.journalId !== journal.id || record.source !== entry.sourceId || record.journalSha256 !== hash(bytes)) throw new Error('Closeout provenance mismatch')
+  const closedAt = readOperationalTime(record.closedAt)
+  if (Date.parse(closedAt) > now + skew * 1000 || Date.parse(closedAt) < Date.parse(start)) throw new Error('Invalid closeout clock')
+  if (JSON.stringify([...record.dates].sort()) !== JSON.stringify(dates)) throw new Error('Closeout dates differ')
+  const n = record.steps?.normalise
+  if (!n || n.unsupported || !Array.isArray(n.skipped) || n.skipped.length) return result('archive', 'degraded', 'archive-normalization-incomplete')
+  let files = 0
+  for (const d of dates) {
+    if (entry.sourceId === 'bulk-archive' && (!record.steps.packs?.[d] || record.steps.packs[d].error)) return result('archive', 'degraded', 'archive-packs-incomplete')
+    const upload = record.steps.upload?.[d]
+    if (!upload) return pending('archive', plan.deadlineAt, now, 'archive-upload')
+    for (const key of ['normalized', 'publish']) {
+      const u = upload[key]
+      if (key === 'publish' && u === null && entry.sourceId !== 'bulk-archive') continue
+      if (!u) return pending('archive', plan.deadlineAt, now, 'archive-upload')
+      if (u.error || u.stopped || u.failed > 0) return result('archive', 'degraded', 'archive-upload-failed')
+      if (![u.files, u.uploaded, u.skipped, u.failed].every(count) || u.failed !== 0 || u.files < 1 || u.uploaded + u.skipped !== u.files) throw new Error('Invalid upload accounting')
+      files += u.files
+    }
+  }
+  return result('archive', 'healthy', 'archive-closeout-verified', { latestPeriodEnd: end, lastSuccessAt: closedAt }, { 'recorded-upload-files': files })
+}
+
+async function publication(plan, read, now, skew) {
+  const { bytes: pointerBytes, json: pointer } = await read(plan.pointerPath, 8192)
+  if (pointer.schemaVersion !== 1 || pointer.kind !== 'feed-quality-release-pointer' || !digest(pointer.resultId) || pointer.operator !== plan.operator) throw new Error('Invalid release pointer')
+  const observedAt = readOperationalTime(pointer.observedAt), from = date(pointer.from), to = date(pointer.to)
+  if (Date.parse(observedAt) > now + skew * 1000 || from > to) throw new Error('Invalid publication clock/range')
+  // The caller selects the pointer; only a validated digest can select its sibling immutable artifact.
+  const dir = join(dirname(dirname(plan.pointerPath)), 'quality-releases', pointer.resultId)
+  const { json: manifest } = await read(join(dir, 'manifest.json'), 4096)
+  const file = manifest.files?.[0]
+  if (manifest.schemaVersion !== 1 || manifest.resultId !== pointer.resultId || manifest.files?.length !== 1 || file.path !== 'result.json' || !count(file.bytes) || !digest(file.sha256)) throw new Error('Invalid release manifest')
+  const { bytes, json: release } = await read(join(dir, 'result.json'), 2 * 1024 * 1024)
+  const { resultId, ...payload } = release
+  if (file.bytes !== bytes.length || file.sha256 !== hash(bytes) || resultId !== pointer.resultId || hash(JSON.stringify(payload)) !== resultId) throw new Error('Release integrity mismatch')
+  if (release.schemaVersion !== 2 || release.kind !== 'feed-quality-history' || release.operator !== plan.operator || release.from !== from || release.to !== to || !Array.isArray(release.days) || release.days.length > 366) throw new Error('Release selection mismatch')
+  if (!(await read(plan.pointerPath, 8192)).bytes.equals(pointerBytes)) throw new Error('Release selection changed during check')
+  const days = new Map()
+  for (const d of release.days) {
+    date(d.date)
+    if (days.has(d.date) || d.date < from || d.date > to) throw new Error('Invalid release day membership')
+    days.set(d.date, d)
+  }
+  if (from > plan.expectedThrough || to < plan.expectedThrough || !days.has(plan.expectedThrough)) return pending('publication', plan.deadlineAt, now, 'publication-period')
+  const selected = days.get(plan.expectedThrough)
+  const expected = studyDay(plan.expectedThrough)
+  if (Date.parse(plan.deadlineAt) < Date.parse(expected.endUtc) || Date.parse(expected.endUtc) > now + skew * 1000 || Date.parse(observedAt) < Date.parse(expected.endUtc)) throw new Error('Invalid publication deadline/period')
+  if (selected.status !== 'current') return pending('publication', plan.deadlineAt, now, 'publication-day')
+  if (!digest(selected.revision) || !selected.quality || selected.day?.serviceDate !== plan.expectedThrough || selected.day?.startUtc !== expected.startUtc || selected.day?.endUtc !== expected.endUtc) throw new Error('Invalid selected day')
+  return result('publication', 'healthy', 'publication-artifact-verified', { lastSuccessAt: observedAt, latestPeriodEnd: expected.endUtc }, { 'verified-release-bytes': bytes.length })
+}

package/recorder-observability.d.mts

@@ -0,0 +1,3 @@
+import type { FeedHealth } from './feed-observability.mjs'
+/** Reads only supplied JSON. `now` is the observer's Unix time in milliseconds. */
+export function recorderFeedHealth(registry: unknown, status: unknown, options: { producerId: string; now?: number }): FeedHealth

package/recorder-observability.mjs

@@ -0,0 +1,106 @@
+import { readFeedRegistry, readFeedHealth, readOperationalTime, summarizeFeedStages } from './feed-observability.mjs'
+
+const finite = value => Number.isFinite(value) && value >= 0 && value <= Number.MAX_SAFE_INTEGER
+const time = value => { try { return readOperationalTime(value) } catch { return null } }
+const age = (stamp, now) => (now - Date.parse(stamp)) / 1000
+const stage = (stageId, state, reasons = [], timestamps = {}, metrics = {}) => ({ stageId, state, reasons, timestamps, metrics })
+const metric = (key, value) => finite(value) ? { [key]: value } : {}
+
+/** Projection of recorder status.json. Never read paths, emit raw errors or trust cached ages/state. */
+export function recorderFeedHealth(registryValue, status, { producerId, now = Date.now() } = {}) {
+  const registry = readFeedRegistry(registryValue)
+  const observedAt = new Date(now).toISOString(), entries = registry.feeds.filter(f => f.producerId === producerId)
+  if (!entries.length) throw new Error('Unregistered producer')
+  if (entries.filter(f => f.stages.some(s => s.id === 'analytics')).length > 1) throw new Error('Recorder status supports one analytics feed')
+  const generatedAt = time(status?.generatedAt), reportAge = generatedAt ? age(generatedAt, now) : null
+  const telemetry = { state: status === null ? 'missing' : !generatedAt || reportAge < -registry.clockSkewSeconds ? 'invalid' : reportAge > registry.heartbeatMaxAgeSeconds ? 'stale' : 'current', ageSeconds: reportAge === null ? null : Math.max(0, reportAge) }
+  const unavailable = telemetry.state !== 'current'
+  if (!unavailable && (!Array.isArray(status.feeds) || status.feeds.length > 128 || new Set(status.feeds.map(f => f?.name)).size !== status.feeds.length)) throw new Error('Invalid recorder feed list')
+  const feeds = entries.map(entry => {
+    const f = status?.feeds?.find?.(f => f?.name === entry.producerFeed)
+    const stages = entry.stages.map(def => {
+      if (unavailable) return stage(def.id, 'unknown', [`telemetry-${telemetry.state}`])
+      if (entry.state !== 'active') return stage(def.id, 'unknown', [entry.state])
+      if (!f) return stage(def.id, 'unknown', ['feed-missing'])
+      if (status.storageError) return stage(def.id, 'degraded', ['host-storage-blocked'])
+      if (f.error) return stage(def.id, 'unknown', ['feed-status-unavailable'])
+      if (f.source !== entry.sourceId) return stage(def.id, 'unknown', [f.source ? 'source-mismatch' : 'source-unavailable'])
+      if (def.id === 'capture') return capture(def, f, registry, now, generatedAt)
+      if (def.id === 'normalize') return normalize(def, f, registry, now, generatedAt)
+      if (def.id === 'archive') {
+        // A complete close-out may be local-only. This report cannot prove an R2 upload.
+        const count = f.processing?.incompleteCloseouts, job = f.jobs?.[`process-${entry.producerFeed}`]
+        if (job && job.code !== 0) return stage(def.id, 'degraded', ['processing-job-failed'], {}, metric('incomplete-closeouts', count))
+        return stage(def.id, finite(count) && count > 0 ? 'waiting' : 'unknown', [finite(count) && count > 0 ? 'closeouts-pending' : 'upload-evidence-unavailable'], {}, metric('incomplete-closeouts', count))
+      }
+      if (def.id === 'analytics') return analytics(def, status.analytics, registry, now, generatedAt)
+      // Publication/serving needs separate evidence, even when a local job succeeded.
+      return stage(def.id, 'unknown', ['stage-evidence-unavailable'])
+    })
+    return { feedId: entry.id, configuredState: entry.state, state: entry.state === 'active' ? summarizeFeedStages(stages) : entry.state, stages }
+  })
+  const c = status?.capacity, disk = status?.disk
+  const capacity = unavailable ? { state: 'unknown', reasons: [`telemetry-${telemetry.state}`], metrics: {} } : {
+    state: status.storageError || c?.status === 'paused' || c?.error || c?.remainingCaptureBytes === 0 ? 'degraded' : c?.status === 'open' && finite(disk?.freeBytes) ? 'healthy' : 'unknown',
+    reasons: status.storageError ? ['host-storage-blocked'] : c?.error ? ['ledger-unavailable'] : c?.status === 'paused' ? ['ledger-paused'] : c?.remainingCaptureBytes === 0 ? ['capture-budget-exhausted'] : c?.status === 'open' && finite(disk?.freeBytes) ? [] : ['capacity-evidence-unavailable'],
+    metrics: { ...metric('disk-free-bytes', disk?.freeBytes), ...metric('disk-total-bytes', disk?.totalBytes), ...metric('committed-bytes', c?.usage?.total?.committed),
+      ...metric('reserved-bytes', c?.usage?.total?.reserved), ...metric('remaining-capture-bytes', c?.remainingCaptureBytes), ...metric('estimated-capture-days', c?.estimatedCaptureDays) },
+  }
+  return readFeedHealth({ schemaVersion: 1, kind: 'feed-health', registryId: registry.id, producerId, observedAt, producerGeneratedAt: generatedAt, telemetry, feeds, capacity }, registry)
+}
+
+function capture(def, f, registry, now, generatedAt) {
+  const receivedAt = time(f.lastCaptureAt)
+  if (!receivedAt) return stage(def.id, 'unknown', ['capture-time-unavailable'])
+  const receivedAge = age(receivedAt, now), timestamps = { receivedAt }, metrics = { 'capture-age-seconds': Math.max(0, receivedAge) }
+  if (receivedAge < -registry.clockSkewSeconds || Date.parse(receivedAt) > Date.parse(generatedAt) + registry.clockSkewSeconds * 1000) return stage(def.id, 'unknown', ['capture-clock-invalid'])
+  const reasons = []
+  if (def.maxAgeSeconds === null) return stage(def.id, 'unknown', ['capture-threshold-unconfigured'], timestamps, metrics)
+  if (receivedAge > def.maxAgeSeconds) reasons.push('capture-stale')
+  // Legacy host status stores source age at report time, not the original timestamp.
+  // Advancing it by report age prevents a fresh read from making old source data fresh.
+  if (finite(f.sourceAgeSeconds)) {
+    const sourceGeneratedAt = new Date(Date.parse(generatedAt) - f.sourceAgeSeconds * 1000)
+    if (!Number.isFinite(sourceGeneratedAt.getTime())) return stage(def.id, 'unknown', ['source-clock-invalid'], timestamps, metrics)
+    timestamps.sourceGeneratedAt = sourceGeneratedAt.toISOString()
+    metrics['source-age-seconds'] = Math.max(0, age(timestamps.sourceGeneratedAt, now))
+    if (def.sourceMaxAgeSeconds && metrics['source-age-seconds'] > def.sourceMaxAgeSeconds) reasons.push('source-stale')
+  } else if (def.sourceMaxAgeSeconds) {
+    return stage(def.id, reasons.length ? 'degraded' : 'unknown', [...reasons, 'source-time-unavailable'], timestamps, metrics)
+  }
+  if (f.plan?.action === 'blocked') reasons.push('collection-blocked')
+  if (reasons.length) return stage(def.id, 'degraded', reasons, timestamps, metrics)
+  if (['complete', 'stopped'].includes(f.state) || f.plan?.action === 'wait') return stage(def.id, 'waiting', ['collection-between-runs'], timestamps, metrics)
+  if (!['healthy', 'stalled'].includes(f.state)) return stage(def.id, 'unknown', ['collection-state-unrecognized'], timestamps, metrics)
+  return stage(def.id, 'healthy', [], timestamps, metrics)
+}
+
+function normalize(def, f, registry, now, generatedAt) {
+  const hour = f.processing?.latestNormalizedHour
+  const start = typeof hour === 'string' && /^\d{4}-\d\d-\d\dT\d\d$/.test(hour) ? time(`${hour}:00:00Z`) : null
+  if (!start) return stage(def.id, 'unknown', ['normalized-period-unavailable'])
+  const latestPeriodEnd = new Date(Date.parse(start) + 3600000).toISOString(), lag = age(latestPeriodEnd, now)
+  if (lag < -registry.clockSkewSeconds || Date.parse(latestPeriodEnd) > Date.parse(generatedAt) + registry.clockSkewSeconds * 1000) return stage(def.id, 'unknown', ['normalized-period-in-future'])
+  const timestamps = { latestPeriodEnd }, metrics = { 'normalization-lag-seconds': Math.max(0, lag) }
+  if (def.maxAgeSeconds === null) return stage(def.id, 'unknown', ['normalization-threshold-unconfigured'], timestamps, metrics)
+  return stage(def.id, lag > def.maxAgeSeconds ? 'degraded' : 'healthy', lag > def.maxAgeSeconds ? ['normalization-lagging'] : [], timestamps, metrics)
+}
+
+function analytics(def, a, registry, now, generatedAt) {
+  const attemptedAt = time(a?.observedAt)
+  if (!attemptedAt) return stage(def.id, 'unknown', ['analytics-status-unavailable'])
+  const elapsed = age(attemptedAt, now)
+  if (elapsed < -registry.clockSkewSeconds || Date.parse(attemptedAt) > Date.parse(generatedAt) + registry.clockSkewSeconds * 1000) return stage(def.id, 'unknown', ['analytics-clock-invalid'])
+  const timestamps = { lastAttemptAt: attemptedAt }
+  if (def.maxAgeSeconds === null) return stage(def.id, 'unknown', ['analytics-threshold-unconfigured'], timestamps)
+  if (elapsed > def.maxAgeSeconds) return stage(def.id, 'unknown', ['analytics-status-stale'], timestamps)
+  if (a.error || a.job && a.job.code !== 0) return stage(def.id, 'degraded', ['analytics-job-failed'], timestamps)
+  if (!Array.isArray(a.pendingMonths) || !Array.isArray(a.waiting) || !a.months || typeof a.months !== 'object' || Array.isArray(a.months) || Object.keys(a.months).length > 120) return stage(def.id, 'unknown', ['analytics-status-invalid'], timestamps)
+  const months = Object.values(a.months), successes = months.map(m => time(m?.lastSuccessAt)).filter(Boolean).sort()
+  if (successes.length) timestamps.lastSuccessAt = successes.at(-1)
+  if (timestamps.lastSuccessAt && (age(timestamps.lastSuccessAt, now) < -registry.clockSkewSeconds || Date.parse(timestamps.lastSuccessAt) > Date.parse(generatedAt) + registry.clockSkewSeconds * 1000)) return stage(def.id, 'unknown', ['analytics-clock-invalid'])
+  const metrics = { 'pending-months': a.pendingMonths.length, 'waiting-inputs': a.waiting.length }
+  // Open receipt hours normally remain waiting. A fresh worker check with no work is not a failed publication.
+  const waiting = a.pendingMonths.length > 0 || a.waiting.length > 0
+  return stage(def.id, waiting ? 'waiting' : successes.length ? 'healthy' : 'unknown', waiting ? ['analytics-awaiting-inputs-or-work'] : successes.length ? [] : ['analytics-success-unavailable'], timestamps, metrics)
+}

package/release-files.d.mts

@@ -0,0 +1,14 @@
+import type { ReleaseDescriptor } from './release.mjs'
+export interface ReleaseOpenOptions { kind?: string; schemaVersions?: readonly number[]; manifestSha256?: string; maxManifestBytes?: number; manifest?: string }
+export interface OpenedRelease<M = Record<string, unknown>> {
+  manifest: M
+  manifestBytes: Buffer
+  descriptors: ReleaseDescriptor[]
+  /** Read a file the manifest describes, by path or descriptor, checking size and digest. */
+  read(file: string | ReleaseDescriptor, options?: { maxBytes?: number }): Promise<Buffer>
+}
+/** Bounded read without following a final symlink or blocking on a FIFO. */
+export function readOperationalFile(path: string, limit: number): Promise<Buffer>
+export function readReleaseFile(root: string, descriptor: ReleaseDescriptor, options?: { maxBytes?: number }): Promise<Buffer>
+export function openRelease<M = Record<string, unknown>>(root: string, options?: ReleaseOpenOptions): Promise<OpenedRelease<M>>
+export function verifyRelease<M = Record<string, unknown>>(root: string, options?: ReleaseOpenOptions & { maxTotalBytes?: number }): Promise<{ manifest: M; manifestSha256: string; files: number; bytes: number }>

package/release-files.mjs

@@ -0,0 +1,47 @@
+import { realpath } from 'node:fs/promises'
+import { join, relative, isAbsolute, resolve, sep } from 'node:path'
+import { readOperationalFile } from './operational-files.mjs'
+import { checkReleaseManifest, digestHex, isReleasePath, readDescriptor, releaseDescriptors, verifyDescriptorBytes } from './release.mjs'
+
+export { readOperationalFile }
+const inside = (root, path) => { const r = relative(root, path); return r !== '' && !r.startsWith(`..${sep}`) && r !== '..' && !isAbsolute(r) }
+
+/** Read one described file from a release directory: safe path, no escape through links, bounded, size and digest checked. */
+export async function readReleaseFile(root, descriptor, { maxBytes = 512 * 1024 ** 2 } = {}) {
+  const d = readDescriptor(descriptor)
+  if (d.bytes > maxBytes) throw new Error(`${d.path} exceeds the read limit`)
+  const base = await realpath(resolve(root)), actual = await realpath(join(base, ...d.path.split('/')))
+  if (!inside(base, actual)) throw new Error(`${d.path} resolves outside the release`)
+  return verifyDescriptorBytes(await readOperationalFile(actual, d.bytes), d)
+}
+
+/**
+ * Open a release directory: read `manifest.json` (bounded), optionally require its pinned digest, check its kind and
+ * schema, and enumerate its files. Nothing but the manifest is read until asked.
+ */
+export async function openRelease(root, { kind, schemaVersions, manifestSha256, maxManifestBytes = 8 * 1024 ** 2, manifest: name = 'manifest.json' } = {}) {
+  if (!isReleasePath(name)) throw new Error('Unsafe manifest path')
+  const bytes = await readOperationalFile(join(resolve(root), name), maxManifestBytes)
+  if (manifestSha256 !== undefined && await digestHex(bytes) !== manifestSha256) throw new Error('Release manifest does not match its pinned digest')
+  const manifest = checkReleaseManifest(JSON.parse(bytes.toString('utf8')), { kind, schemaVersions })
+  const descriptors = releaseDescriptors(manifest), byPath = new Map(descriptors.map(d => [d.path, d]))
+  return {
+    manifest, manifestBytes: bytes, descriptors,
+    /** Read a described file by path or descriptor; a path the manifest does not list is refused. */
+    read: async (file, options) => {
+      const d = typeof file === 'string' ? byPath.get(file) : file
+      const listed = d && byPath.get(d.path)
+      if (!listed || listed.sha256 !== d.sha256 || listed.bytes !== d.bytes) throw new Error(`${typeof file === 'string' ? file : file?.path} is not described by the manifest`)
+      return readReleaseFile(root, d, options)
+    },
+  }
+}
+
+/** Verify every file a release describes against a total byte budget. */
+export async function verifyRelease(root, { maxTotalBytes = 2 * 1024 ** 3, ...options } = {}) {
+  const release = await openRelease(root, options)
+  const total = release.descriptors.reduce((n, d) => n + d.bytes, 0)
+  if (total > maxTotalBytes) throw new Error('Release exceeds the verification budget')
+  for (const d of release.descriptors) await readReleaseFile(root, d)
+  return { manifest: release.manifest, manifestSha256: await digestHex(release.manifestBytes), files: release.descriptors.length, bytes: total }
+}

package/release.d.mts

@@ -0,0 +1,10 @@
+/** A file a release describes: its release-relative path and the size and SHA-256 of its stored bytes. */
+export interface ReleaseDescriptor { path: string; sha256: string; bytes: number; [field: string]: unknown }
+export declare const RELEASE_DIGEST: RegExp
+export function isReleasePath(path: unknown): path is string
+export function readDescriptor(value: unknown, label?: string): ReleaseDescriptor
+/** Every descriptor in a manifest's `files` (array or map), `objects`, `chunks`, `list` and named top-level descriptors, sorted by path. */
+export function releaseDescriptors(manifest: unknown): ReleaseDescriptor[]
+export function checkReleaseManifest<T extends object>(manifest: T, options: { kind?: string; schemaVersions?: readonly number[] }): T
+export function digestHex(bytes: ArrayBuffer | ArrayBufferView): Promise<string>
+export function verifyDescriptorBytes<T extends ArrayBuffer | ArrayBufferView>(bytes: T, descriptor: ReleaseDescriptor): Promise<T>

package/release.mjs

@@ -0,0 +1,62 @@
+// Shared checks for versioned release handoffs. Runs in Node and in browsers (Web Crypto only).
+
+export const RELEASE_DIGEST = /^[a-f0-9]{64}$/
+const SEGMENT = /^[A-Za-z0-9._-]{1,255}$/
+
+/** A release-relative path: forward-slash segments of safe characters, never absolute, empty, `.` or `..`. */
+export function isReleasePath(path) {
+  return typeof path === 'string' && path.length <= 1024 && path.split('/').every(s => SEGMENT.test(s) && s !== '.' && s !== '..')
+}
+
+/** Validate one `{ path, sha256, bytes }` file descriptor; extra fields such as `decodedBytes` are kept. */
+export function readDescriptor(value, label = 'file') {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`Invalid ${label} descriptor`)
+  if (!isReleasePath(value.path)) throw new Error(`Unsafe ${label} path`)
+  if (!RELEASE_DIGEST.test(value.sha256 ?? '')) throw new Error(`Invalid ${label} digest`)
+  if (!Number.isSafeInteger(value.bytes) || value.bytes < 0) throw new Error(`Invalid ${label} size`)
+  return value
+}
+
+const looksLikeDescriptor = v => v && typeof v === 'object' && !Array.isArray(v) && typeof v.path === 'string' && 'sha256' in v && 'bytes' in v
+/**
+ * Every file a manifest describes, whatever its layout: a `files` array or name-keyed map, an `objects` map keyed by
+ * digest, `chunks`, a published bus day's `list`, and named top-level descriptors such as `day` or `index`. The same
+ * path may appear more than once (air releases list chunks in `files` and `chunks`) but must then describe the same
+ * bytes.
+ */
+export function releaseDescriptors(manifest) {
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) throw new Error('Invalid release manifest')
+  const found = new Map()
+  const add = (value, label) => {
+    const d = readDescriptor(value, label), seen = found.get(d.path)
+    if (seen && (seen.sha256 !== d.sha256 || seen.bytes !== d.bytes)) throw new Error(`Conflicting descriptors for ${d.path}`)
+    if (!seen) found.set(d.path, d)
+  }
+  for (const [key, value] of Object.entries(manifest)) {
+    if (Array.isArray(value) && ['files', 'chunks', 'list'].includes(key)) value.forEach((v, i) => add(v, `${key}[${i}]`))
+    else if (['files', 'objects'].includes(key) && value && typeof value === 'object' && !Array.isArray(value)) for (const [name, v] of Object.entries(value)) add(v, `${key}.${name}`)
+    else if (looksLikeDescriptor(value)) add(value, key)
+  }
+  return [...found.values()].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0)
+}
+
+/** Check a manifest's identity before trusting its layout. */
+export function checkReleaseManifest(manifest, { kind, schemaVersions }) {
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) throw new Error('Invalid release manifest')
+  if (kind !== undefined && manifest.kind !== kind) throw new Error(`Expected a ${kind} release`)
+  if (schemaVersions !== undefined && !schemaVersions.includes(manifest.schemaVersion)) throw new Error(`Unsupported ${manifest.kind ?? 'release'} schema version`)
+  return manifest
+}
+
+const hex = buffer => Array.from(new Uint8Array(buffer), b => b.toString(16).padStart(2, '0')).join('')
+/** SHA-256 of bytes as lowercase hex, through Web Crypto. */
+export async function digestHex(bytes) {
+  return hex(await globalThis.crypto.subtle.digest('SHA-256', bytes))
+}
+/** Throw unless `bytes` are exactly the descriptor's size and digest. */
+export async function verifyDescriptorBytes(bytes, descriptor) {
+  const d = readDescriptor(descriptor)
+  if (bytes.byteLength !== d.bytes) throw new Error(`${d.path} has ${bytes.byteLength} bytes, expected ${d.bytes}`)
+  if (await digestHex(bytes) !== d.sha256) throw new Error(`${d.path} does not match its digest`)
+  return bytes
+}

package/uk-service-day.d.mts

@@ -1,3 +1,4 @@
+export declare const SERVICE_TIMEZONE: 'Europe/London'
 /** UK civil day boundaries. GTFS service time has a separate noon-based origin. */
 export interface UkStudyDay {serviceDate:string;timezone:'Europe/London';startUtc:string;endUtc:string;durationSeconds:number}
 export function checkedDate(value:string):string

package/uk-service-day.mjs

@@ -1,4 +1,4 @@
-const TIMEZONE = 'Europe/London'
+export const SERVICE_TIMEZONE = 'Europe/London'
 
 export function checkedDate(value) {
   if (!/^\d{4}-\d{2}-\d{2}$/.test(value ?? '') || !Number.isFinite(Date.parse(`${value}T00:00:00Z`)) ||
@@ -11,7 +11,7 @@ export function checkedDate(value) {
 // UK midnight is unambiguous on both DST transition days. Never infer a full day as 86400 seconds.
 function londonMidnight(date) {
   const nominal = Date.parse(`${date}T00:00:00Z`)
-  const formatter = new Intl.DateTimeFormat('en-GB', { timeZone: TIMEZONE, timeZoneName: 'longOffset' })
+  const formatter = new Intl.DateTimeFormat('en-GB', { timeZone: SERVICE_TIMEZONE, timeZoneName: 'longOffset' })
   let instant = nominal
   for (let attempt = 0; attempt < 3; attempt++) {
     const offset = formatter.formatToParts(instant).find(part => part.type === 'timeZoneName').value
@@ -28,7 +28,7 @@ export function studyDay(serviceDate) {
   const next = new Date(Date.parse(`${serviceDate}T00:00:00Z`) + 86400000).toISOString().slice(0, 10)
   const start = londonMidnight(serviceDate)
   const end = londonMidnight(next)
-  return { serviceDate, timezone: TIMEZONE, startUtc: new Date(start).toISOString(), endUtc: new Date(end).toISOString(), durationSeconds: (end - start) / 1000 }
+  return { serviceDate, timezone: SERVICE_TIMEZONE, startUtc: new Date(start).toISOString(), endUtc: new Date(end).toISOString(), durationSeconds: (end - start) / 1000 }
 }
 
 export function utcDatesForDay(day) {