model-eol 0.5.2 → 0.6.0

package/SPEC.md

@@ -49,7 +49,9 @@ A feed is a JSON document: metadata + a list of model entries.
 | `replacement_note` | no | Free-text guidance such as parameter requirements or provider platform alternatives |
 | `notes` | no | Human context: structural differences, migration gotchas |
 | `distributions` | no | Per-distributor lifecycles - the same weights on different clocks (Azure, Bedrock, Vertex). Each entry: `via`, optional `announced`/`shutdown`/`status`/`date_precision`, `source` |
-| `date_precision` | no | Qualifies `shutdown`: absent or `"exact"` means the stated day; `"earliest"` means the provider commits only that the event happens no sooner (Google's "earliest possible" dates). Consumers treat an earliest date as the scheduled date - it is the soonest legal death - and display it as a lower bound |
+| `date_precision` | no | Qualifies `shutdown`: absent or `"exact"` means the stated day; `"earliest"` is a scheduled date that cannot move earlier; `"tentative"` means the publisher lists a not-before retirement date without announcing deprecation |
+
+Tentative entries carry no `announced`. Consumers must not treat their dates as scheduled retirements. The reference checker reports them as `scheduled` and never fails on them.
 
 Dates are ISO 8601, UTC. A model with no `announced` and no `shutdown` is an
 affirmative statement of "no retirement scheduled as of `generated`" - the absence
@@ -134,6 +136,15 @@ per lifecycle channel, with a deterministic channel-qualified `bom-ref`. This
 keeps direct publisher and distributor clocks distinct and binds each source
 occurrence to the lifecycle decision that evaluated it.
 
+**Compatibility within 0.1.** The `model-eol/0.1` line evolves additively: new
+optional fields and new enumeration values (such as `date_precision:
+"tentative"`, added in 2026-09) may appear in feeds and reports without a
+version change. A consumer that validates strictly against a snapshot of these
+schemas should expect to refresh that snapshot when it upgrades, and a consumer
+that reads defensively should ignore fields and values it does not recognise
+rather than reject the document. Removing a field or changing the meaning of an
+existing value is a new spec line.
+
 ## Non-goals (v0.1)
 
 Pricing, capabilities, context windows (models.dev and friends already do this);

package/bot/bot.mjs

@@ -8,6 +8,7 @@ import { fileURLToPath } from 'node:url'
 import { isDeepStrictEqual } from 'node:util'
 
 import {
+  activeWaiver,
   branchFor,
   daysRemaining,
   hasMetadataMarker,
@@ -20,6 +21,7 @@ import {
   parseMetadata,
   repoPath,
   sha256,
+  staleWorkComment,
   stableJson,
 } from './lib/common.mjs'
 import { assertValidPlanDocument } from '../lib/validate-document.mjs'
@@ -342,6 +344,7 @@ const buildModelGroups = (plan, config, root, records) => {
   const ignoredIds = ignoredModelIds(plan, config)
   const groups = new Map()
   for (const item of plan.items) {
+    if (activeWaiver(item)) continue
     if (isIgnored(item, root, config, ignoredIds)) continue
     const via = Object.hasOwn(item, 'requested_via') ? item.requested_via : plan.via
     const key = `${item.publisher}\0${item.id}\0${via ?? ''}`
@@ -369,6 +372,7 @@ const buildIssueGroups = (plan, config, root, records) => {
   const ignoredIds = ignoredModelIds(plan, config)
   const groups = new Map()
   for (const issue of plan.issues) {
+    if (activeWaiver(issue)) continue
     if (!ISSUE_REASONS.has(issue.reason)) continue
     if (issue.reason !== 'unresolved-channel' && !ACTIONABLE_STATUSES.has(issue.status)) continue
     if (isIgnored(issue, root, config, ignoredIds)) continue
@@ -640,8 +644,6 @@ const ownedIssueRecords = issues => issues
   .map(item => ({ item, metadata: parseMetadata(item.body) }))
   .filter(record => record.metadata)
 
-const staleWorkComment = kind => `model-eol is closing this bot-owned ${kind} because its finding is no longer actionable on the repository's current default branch. The reference may have been removed, ignored, retracted by the feed, moved to another clock, or disabled by repository configuration.`
-
 const staleClosedBody = (body, metadata) => {
   const lines = String(body ?? '').split(/\r?\n/)
   lines[0] = metadataLine({ ...metadata, stale_closed: true })
@@ -657,7 +659,7 @@ const groupFromMetadata = (kind, metadata) => ({
   branch: kind === 'model' ? branchFor(metadata.publisher, metadata.id, metadata.via ?? null) : undefined,
 })
 
-const reconcileStaleWork = async ({ api, pulls, issues, models, issueGroups }) => {
+const reconcileStaleWork = async ({ api, pulls, issues, models, issueGroups, plan }) => {
   const activeModels = new Set(models.map(group => modelIdentity(group.publisher, group.id, group.via)))
   const activeIssues = new Set(issueGroups.flatMap(group => {
     const exact = issueIdentity(group.publisher, group.id || group.subject, group.via, group.channel)
@@ -665,12 +667,23 @@ const reconcileStaleWork = async ({ api, pulls, issues, models, issueGroups }) =
       ? [exact]
       : [exact, issueIdentity(group.publisher, group.id || group.subject, group.via, null)]
   }))
+  const waivedModels = new Map()
+  const waivedIssues = new Map()
+  for (const item of [...plan.items, ...plan.issues]) {
+    const waiver = activeWaiver(item)
+    if (!waiver || !item.id || !item.publisher) continue
+    const via = Object.hasOwn(item, 'requested_via') ? item.requested_via : (item.via ?? plan.via)
+    const modelKey = modelIdentity(item.publisher, item.id, via)
+    const issueKey = issueIdentity(item.publisher, item.id, via, null)
+    if (!waivedModels.has(modelKey)) waivedModels.set(modelKey, waiver)
+    if (!waivedIssues.has(issueKey)) waivedIssues.set(issueKey, waiver)
+  }
   const decisions = []
   for (const record of ownedPullRecords(pulls, api.repo)) {
     if (!isOpen(record.item)) continue
     const key = modelIdentity(record.metadata.publisher, record.metadata.id, record.metadata.via)
     if (activeModels.has(key)) continue
-    await api.comment(record.item.number, staleWorkComment('pull request'))
+    await api.comment(record.item.number, staleWorkComment('pull request', waivedModels.get(key) ?? null))
     await api.updatePull(record.item.number, {
       state: 'closed',
       body: staleClosedBody(record.item.body, record.metadata),
@@ -683,7 +696,7 @@ const reconcileStaleWork = async ({ api, pulls, issues, models, issueGroups }) =
     const legacyKey = issueIdentity(record.metadata.publisher, record.metadata.id, record.metadata.via, null)
     const evalFailure = record.metadata.channel === EVAL_FAILURE_CHANNEL
     if (activeIssues.has(key) || (!evalFailure && activeIssues.has(legacyKey))) continue
-    await api.comment(record.item.number, staleWorkComment('issue'))
+    await api.comment(record.item.number, staleWorkComment('issue', waivedIssues.get(legacyKey) ?? waivedIssues.get(key) ?? null))
     await api.updateIssue(record.item.number, {
       state: 'closed',
       body: staleClosedBody(record.item.body, record.metadata),
@@ -1491,7 +1504,7 @@ export const runBot = async ({
       for (const group of issues) decisions.push(await processIssue({ api, issues: issueRecords, group, now }))
     }
     if (labelReady) {
-      decisions.push(...await reconcileStaleWork({ api, pulls, issues: issueRecords, models, issueGroups: [...issues, ...evalIssueGroups] }))
+      decisions.push(...await reconcileStaleWork({ api, pulls, issues: issueRecords, models, issueGroups: [...issues, ...evalIssueGroups], plan }))
     }
     return { plan, config, decisions, feedsDir: feedSet.dir, degraded: false }
   } finally {

package/bot/lib/common.mjs

@@ -80,6 +80,12 @@ export const parseMetadata = body => {
 
 export const itemDigest = items => sortedJsonDigest(items)
 
+export const activeWaiver = item => item?.waiver?.active === true ? item.waiver : null
+
+export const staleWorkComment = (kind, waiver = null) => waiver
+  ? `model-eol is closing this bot-owned ${kind} because an active waiver makes its finding non-actionable. The waiver expires ${waiver.expires}, is owned by ${markdownText(waiver.owner)}, and records: ${markdownText(waiver.reason)}`
+  : `model-eol is closing this bot-owned ${kind} because its finding is no longer actionable on the repository's current default branch. The reference may have been removed, ignored, retracted by the feed, moved to another clock, or disabled by repository configuration.`
+
 const entityMap = new Map([
   ['&', '&'],
   ['<', '&lt;'],

package/lib/config.mjs

@@ -2,18 +2,23 @@ import fs from 'node:fs'
 import { TextDecoder } from 'node:util'
 
 import { matchesAnyGlob, normalizeRepoPath } from './glob.mjs'
-import { MAX_REPORT_BYTES, MAX_TIMEOUT_MS, MIN_TIMEOUT_MS } from './validate-feed.mjs'
+import { assertIsoDate, MAX_REPORT_BYTES, MAX_TIMEOUT_MS, MIN_TIMEOUT_MS } from './validate-feed.mjs'
 
 const utf8Decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true })
 
 const frozenArray = () => Object.freeze([])
 
+export const MAX_WAIVERS = 500
+
+const PUBLISHER_WAIVER_VIAS = new Set(['publisher', 'publisher-fallback'])
+
 export const DEFAULT_CONFIG = Object.freeze({
   days: 90,
   scope: 'direct',
   via: null,
   feeds: Object.freeze({ allow_vendored_fallback: false }),
   ignore: Object.freeze({ models: frozenArray(), paths: frozenArray() }),
+  waivers: frozenArray(),
   overrides: frozenArray(),
   routes: frozenArray(),
   issues: Object.freeze({ enabled: true }),
@@ -34,6 +39,10 @@ const copyDefaults = defaults => ({
     models: [...defaults.ignore.models],
     paths: [...defaults.ignore.paths],
   },
+  waivers: (defaults.waivers ?? []).map(waiver => ({
+    ...waiver,
+    ...(waiver.paths ? { paths: [...waiver.paths] } : {}),
+  })),
   overrides: (defaults.overrides ?? []).map(override => ({
     ...override,
     paths: [...override.paths],
@@ -41,6 +50,10 @@ const copyDefaults = defaults => ({
       models: [...(override.ignore.models ?? [])],
       paths: [...(override.ignore.paths ?? [])],
     } } : {}),
+    ...(override.waivers ? { waivers: override.waivers.map(waiver => ({
+      ...waiver,
+      ...(waiver.paths ? { paths: [...waiver.paths] } : {}),
+    })) } : {}),
   })),
   routes: (defaults.routes ?? []).map(route => ({ ...route, paths: [...route.paths] })),
   issues: { enabled: defaults.issues.enabled },
@@ -74,6 +87,12 @@ const nonEmptyString = (value, label) => {
   return value
 }
 
+const boundedString = (value, label, limit) => {
+  nonEmptyString(value, label)
+  assert(value.length <= limit, `${label} must be at most ${limit} characters`)
+  return value
+}
+
 const normalizeIgnore = (raw, label) => {
   assert(raw && typeof raw === 'object' && !Array.isArray(raw), `${label} must be an object`)
   assertKnownKeys(raw, label, new Set(['models', 'paths']))
@@ -83,10 +102,36 @@ const normalizeIgnore = (raw, label) => {
   }
 }
 
+const normalizeWaiver = (raw, index, labelPrefix) => {
+  const label = `${labelPrefix}[${index}]`
+  assert(raw && typeof raw === 'object' && !Array.isArray(raw), `${label} must be an object`)
+  assertKnownKeys(raw, label, new Set(['model', 'paths', 'via', 'reason', 'owner', 'expires']))
+  const waiver = {
+    model: nonEmptyString(raw.model, `${label}.model`),
+    reason: boundedString(raw.reason, `${label}.reason`, 500),
+    owner: boundedString(raw.owner, `${label}.owner`, 200),
+    expires: nonEmptyString(raw.expires, `${label}.expires`),
+  }
+  try {
+    assertIsoDate(waiver.expires, `${label}.expires`)
+  } catch (error) {
+    assert(false, error.message)
+  }
+  if (raw.paths !== undefined) waiver.paths = stringArray(raw.paths, `${label}.paths`)
+  if (raw.via !== undefined) waiver.via = nonEmptyString(raw.via, `${label}.via`)
+  return waiver
+}
+
+const normalizeWaivers = (raw, label) => {
+  assert(Array.isArray(raw), `${label} must be an array`)
+  assert(raw.length <= MAX_WAIVERS, `${label} must contain at most ${MAX_WAIVERS} waivers`)
+  return raw.map((waiver, index) => normalizeWaiver(waiver, index, label))
+}
+
 const normalizeOverride = (raw, index) => {
   const label = `overrides[${index}]`
   assert(raw && typeof raw === 'object' && !Array.isArray(raw), `${label} must be an object`)
-  assertKnownKeys(raw, label, new Set(['paths', 'days', 'scope', 'via', 'ignore']))
+  assertKnownKeys(raw, label, new Set(['paths', 'days', 'scope', 'via', 'ignore', 'waivers']))
   const override = { paths: stringArray(raw.paths, `${label}.paths`) }
   assert(override.paths.length > 0, `${label}.paths must not be empty`)
   if (raw.days !== undefined) {
@@ -102,6 +147,7 @@ const normalizeOverride = (raw, index) => {
     override.via = raw.via
   }
   if (raw.ignore !== undefined) override.ignore = normalizeIgnore(raw.ignore, `${label}.ignore`)
+  if (raw.waivers !== undefined) override.waivers = normalizeWaivers(raw.waivers, `${label}.waivers`)
   return override
 }
 
@@ -126,7 +172,7 @@ const CREDENTIAL_ENV_PATTERN = /^(?:GITHUB_|GH_|ACTIONS_|SSH_|AWS_SECRET)|(?:TOK
 
 export const normalizeConfig = (raw, { defaults = DEFAULT_CONFIG } = {}) => {
   assert(raw && typeof raw === 'object' && !Array.isArray(raw), 'root must be an object')
-  assertKnownKeys(raw, '', new Set(['days', 'scope', 'via', 'feeds', 'ignore', 'overrides', 'routes', 'issues', 'eval']))
+  assertKnownKeys(raw, '', new Set(['days', 'scope', 'via', 'feeds', 'ignore', 'waivers', 'overrides', 'routes', 'issues', 'eval']))
   const config = copyDefaults(defaults)
 
   if (raw.days !== undefined) {
@@ -154,10 +200,13 @@ export const normalizeConfig = (raw, { defaults = DEFAULT_CONFIG } = {}) => {
     if (raw.ignore.models !== undefined) config.ignore.models = ignore.models
     if (raw.ignore.paths !== undefined) config.ignore.paths = ignore.paths
   }
+  if (raw.waivers !== undefined) config.waivers = normalizeWaivers(raw.waivers, 'waivers')
   if (raw.overrides !== undefined) {
     assert(Array.isArray(raw.overrides), 'overrides must be an array')
     config.overrides = raw.overrides.map(normalizeOverride)
   }
+  const waiverCount = config.waivers.length + config.overrides.reduce((count, override) => count + (override.waivers?.length ?? 0), 0)
+  assert(waiverCount <= MAX_WAIVERS, `config must contain at most ${MAX_WAIVERS} waivers across the root and overrides`)
   if (raw.routes !== undefined) {
     assert(Array.isArray(raw.routes), 'routes must be an array')
     config.routes = raw.routes.map(normalizeRoute)
@@ -195,6 +244,11 @@ export const normalizeConfig = (raw, { defaults = DEFAULT_CONFIG } = {}) => {
 
 export const configForRepoPath = (config, repoPath) => {
   const normalizedPath = normalizeRepoPath(repoPath)
+  const matchesPath = patterns => matchesAnyGlob(normalizedPath, patterns) || patterns.some(pattern => {
+    const normalizedPattern = normalizeRepoPath(pattern).replace(/\/+$/, '')
+    return normalizedPattern && !/[*?]/.test(normalizedPattern) && normalizedPath.startsWith(`${normalizedPattern}/`)
+  })
+  const applicableWaivers = waivers => (waivers ?? []).filter(waiver => waiver.paths === undefined || matchesPath(waiver.paths))
   const policy = {
     days: config.days,
     scope: config.scope,
@@ -203,6 +257,7 @@ export const configForRepoPath = (config, repoPath) => {
       models: [...config.ignore.models],
       paths: [...config.ignore.paths],
     },
+    waivers: applicableWaivers(config.waivers),
     override_indexes: [],
   }
   for (const [index, override] of (config.overrides ?? []).entries()) {
@@ -215,6 +270,7 @@ export const configForRepoPath = (config, repoPath) => {
       policy.ignore.models.push(...override.ignore.models)
       policy.ignore.paths.push(...override.ignore.paths)
     }
+    policy.waivers.push(...applicableWaivers(override.waivers))
   }
   policy.ignore.models = [...new Set(policy.ignore.models)]
   policy.ignore.paths = [...new Set(policy.ignore.paths)]
@@ -244,6 +300,8 @@ export const configuredVias = config => [
   config.via,
   ...(config.overrides ?? []).map(override => override.via),
   ...(config.routes ?? []).map(route => route.via),
+  ...(config.waivers ?? []).map(waiver => waiver.via).filter(via => !PUBLISHER_WAIVER_VIAS.has(via)),
+  ...(config.overrides ?? []).flatMap(override => (override.waivers ?? []).map(waiver => waiver.via).filter(via => !PUBLISHER_WAIVER_VIAS.has(via))),
 ].filter(via => typeof via === 'string' && via.length > 0)
 
 export const loadConfig = (file, { defaults = DEFAULT_CONFIG, allowMissing = true } = {}) => {

package/lib/feeds.mjs

@@ -127,6 +127,11 @@ export const lifecycleFor = (entry, options) => {
   } = options
   const sd = effectiveShutdown(entry, via)
   if (sd) {
+    const distribution = via
+      ? (entry.distributions ?? []).find(d => d.via === via)
+      : null
+    const publisherClock = sd.via === 'publisher' || sd.via === 'publisher-fallback'
+    const announced = publisherClock ? entry.announced : distribution?.announced
     if (sd.distribution_status === 'retired') {
       return {
         status: 'retired',
@@ -138,6 +143,19 @@ export const lifecycleFor = (entry, options) => {
         safe_until: sd.date,
       }
     }
+    if (sd.date && sd.date_precision === 'tentative' && !announced) {
+      const policyFloor = publisherClock ? policySafeUntil(policy, generated) : null
+      const safeUntil = policyFloor && policyFloor > sd.date ? policyFloor : sd.date
+      return {
+        status: 'scheduled',
+        shutdown: sd.date,
+        date_precision: sd.date_precision,
+        distribution_status: sd.distribution_status,
+        via: sd.via,
+        days: daysUntil(safeUntil, today),
+        safe_until: safeUntil,
+      }
+    }
     if (sd.date) {
       const remaining = daysUntil(sd.date, today)
       return {
@@ -150,10 +168,6 @@ export const lifecycleFor = (entry, options) => {
         safe_until: sd.date,
       }
     }
-    const distribution = via
-      ? (entry.distributions ?? []).find(d => d.via === via)
-      : null
-    const announced = distribution?.announced ?? (sd.via === 'publisher-fallback' ? entry.announced : null)
     const status = announced ? 'watch' : 'ok'
     return {
       status,
@@ -196,7 +210,20 @@ export const findingFromRef = (ref, options) => {
     policy,
     generated,
   })
-  return {
+  const family = new Set([ref.entry.id, ...(ref.entry.aliases ?? [])])
+  const matchingWaivers = (ref.waivers ?? []).filter(waiver =>
+    family.has(waiver.model) && (waiver.via === undefined || waiver.via === lifecycle.via))
+  const todayDate = today.toISOString().slice(0, 10)
+  const selectedWaiver = matchingWaivers.find(waiver => todayDate < waiver.expires) ?? matchingWaivers[0] ?? null
+  const waiver = selectedWaiver
+    ? {
+        reason: selectedWaiver.reason,
+        owner: selectedWaiver.owner,
+        expires: selectedWaiver.expires,
+        active: todayDate < selectedWaiver.expires,
+      }
+    : null
+  const finding = {
     file: ref.file,
     line: ref.line,
     matched: ref.matched,
@@ -216,7 +243,10 @@ export const findingFromRef = (ref, options) => {
     replacement_options: ref.entry.replacement_options ?? null,
     replacement_note: ref.entry.replacement_note ?? null,
     threshold_days: days,
+    ...(waiver ? { waiver } : {}),
   }
+  return finding
 }
 
-export const isBad = finding => finding.status === 'retired' || finding.status === 'retiring'
+export const isBad = finding =>
+  (finding.status === 'retired' || finding.status === 'retiring') && finding.waiver?.active !== true

package/lib/plan.mjs

@@ -46,6 +46,7 @@ const issueFor = (ref, finding, reason, via) => ({
   replacement: finding.replacement,
   ...(finding.replacement_options?.length ? { replacement_options: finding.replacement_options } : {}),
   ...(finding.replacement_note ? { replacement_note: finding.replacement_note } : {}),
+  ...(finding.waiver ? { waiver: finding.waiver } : {}),
   reason,
   sources: sourceList(ref, finding, via),
   notes: notesFor(ref),
@@ -77,6 +78,11 @@ export const buildPlan = ({ scan, findings, entries, days, via, scope }) => {
     const effectiveVia = requestedVia(finding, via)
     const effectiveDays = finding.threshold_days ?? days
 
+    if (finding.waiver?.active) {
+      issues.push(issueFor(ref, finding, 'waived', effectiveVia))
+      return
+    }
+
     let reason
     if (finding.status === 'watch') reason = 'watch'
     else if (finding.status !== 'retired' && finding.status !== 'retiring') reason = 'outside-threshold'
@@ -133,6 +139,7 @@ export const buildPlan = ({ scan, findings, entries, days, via, scope }) => {
       effective_scope: finding.effective_scope ?? scope,
       ...(finding.policy_provenance ? { policy_provenance: finding.policy_provenance } : {}),
       ...(ref.mapped_from ? { mapped_from: ref.mapped_from } : {}),
+      ...(finding.waiver ? { waiver: finding.waiver } : {}),
       sources: sourceList(ref, finding, effectiveVia),
       notes: notesFor(ref),
     })

package/lib/reports.mjs

@@ -8,9 +8,16 @@ export const marker = status =>
   status === 'watch' ? '?' :
   '·'
 
-const shutdownText = finding => finding.date_precision === 'earliest'
-  ? `no earlier than ${finding.shutdown}`
-  : finding.shutdown
+const shutdownText = finding =>
+  finding.date_precision === 'tentative' ? `not sooner than ${finding.shutdown}` :
+  finding.date_precision === 'earliest' ? `no earlier than ${finding.shutdown}` :
+  finding.shutdown
+
+const tentativeFloor = finding => finding.date_precision === 'tentative'
+
+const policyTail = finding => finding.safe_until && finding.shutdown && finding.safe_until > finding.shutdown
+  ? `, guaranteed until ${finding.safe_until} by ${finding.publisher} policy`
+  : ''
 
 const replacementTail = finding => finding.replacement
   ? ` -> ${finding.replacement}`
@@ -18,22 +25,32 @@ const replacementTail = finding => finding.replacement
     ? ` options: ${finding.replacement_options.join(' | ')}`
     : ''
 
-export const findingTail = (f, days) =>
+const lifecycleTail = (f, days) =>
   f.status === 'retired' && !f.shutdown ? `RETIRED (shutdown date unavailable)${replacementTail(f)}` :
   f.status === 'retired' ? `RETIRED ${shutdownText(f)} (${-f.days} days ago)${replacementTail(f)}` :
   f.status === 'retiring' ? `RETIRES ${shutdownText(f)} (${f.days} days)${replacementTail(f)}` :
+  tentativeFloor(f) ? `scheduled - tentative, not announced: ${shutdownText(f)}${policyTail(f)}` :
   f.status === 'scheduled' ? `scheduled ${shutdownText(f)} (${f.days} days, outside --days ${f.threshold_days ?? days})` :
   f.status === 'watch' ? 'deprecation announced, no shutdown date yet' :
   'no retirement scheduled'
 
-const statusStyle = status =>
-  status === 'retired' ? 'red' :
-  status === 'retiring' ? 'yellow' :
-  status === 'ok' ? 'dim' :
+const waiverTail = finding => !finding.waiver
+  ? ''
+  : finding.waiver.active
+    ? `  [waived until ${finding.waiver.expires} by ${finding.waiver.owner}: ${finding.waiver.reason}]`
+    : `  [waiver expired on ${finding.waiver.expires}; owner ${finding.waiver.owner}: ${finding.waiver.reason}]`
+
+export const findingTail = (finding, days) => `${lifecycleTail(finding, days)}${waiverTail(finding)}`
+
+const statusStyle = finding =>
+  finding.waiver?.active === true ? 'yellow' :
+  finding.status === 'retired' ? 'red' :
+  finding.status === 'retiring' ? 'yellow' :
+  finding.status === 'ok' ? 'dim' :
   null
 
-const humanFinding = (status, line) => {
-  const style = statusStyle(status)
+const humanFinding = (finding, line) => {
+  const style = statusStyle(finding)
   return style ? color(style, line) : line
 }
 
@@ -67,6 +84,7 @@ export const buildInventory = ({ scan, findings, days, via, scope, targets }) =>
       replacement: lifecycle.replacement,
       ...(lifecycle.replacement_options?.length ? { replacement_options: lifecycle.replacement_options } : {}),
       ...(lifecycle.replacement_note ? { replacement_note: lifecycle.replacement_note } : {}),
+      ...(lifecycle.waiver ? { waiver: lifecycle.waiver } : {}),
       source: ref.source,
       policy: ref.policy ?? null,
       feed_generated: ref.generated ?? null,
@@ -149,9 +167,11 @@ export const buildSchedule = inventory => {
 }
 
 export const buildAlert = schedule => {
-  const errors = schedule.items.filter(item => item.status === 'retired' || item.status === 'retiring')
+  const errors = schedule.items.filter(isBad)
   const warnings = [
-    ...schedule.items.filter(item => item.status === 'scheduled' || item.status === 'watch'),
+    ...schedule.items.filter(item =>
+      item.status === 'scheduled' || item.status === 'watch' ||
+      ((item.status === 'retired' || item.status === 'retiring') && item.waiver?.active === true)),
     ...schedule.candidate_model_references.map(item => ({ ...item, status: 'unknown' })),
     ...schedule.unresolved_integrations.map(item => ({ ...item, status: 'unresolved' })),
   ]
@@ -174,7 +194,7 @@ export const formatCheck = ({ findings, bad, scannedFiles, days, scope }) => {
   }
   for (const f of findings) {
     const where = `${f.file}:${f.line}`
-    out.push(humanFinding(f.status, `${marker(f.status)} ${where}  ${f.matched}  ${findingTail(f, days)}${f.via && f.via !== 'publisher' ? `  [via ${f.via}]` : ''}`))
+    out.push(humanFinding(f, `${marker(f.status)} ${where}  ${f.matched}  ${findingTail(f, days)}${f.via && f.via !== 'publisher' ? `  [via ${f.via}]` : ''}`))
   }
   if (bad.length) out.push(`\n${color('bold', `model-eol: ${bad.length} finding(s) at or past the ${days}-day threshold`)}`)
   return out.join('\n')
@@ -187,7 +207,7 @@ export const formatInventory = (inventory, days) => {
   if (inventory.model_references.length) {
     out.push('\nModel references')
     for (const item of inventory.model_references) {
-      out.push(humanFinding(item.status, `${marker(item.status)} ${item.file}:${item.line}  ${item.matched}  ${item.publisher}/${item.id}  ${item.usage}  ${findingTail(item, days)}`))
+      out.push(humanFinding(item, `${marker(item.status)} ${item.file}:${item.line}  ${item.matched}  ${item.publisher}/${item.id}  ${item.usage}  ${findingTail(item, days)}`))
     }
   }
   if (inventory.candidate_model_references.length) {
@@ -212,7 +232,7 @@ export const formatSchedule = (schedule, days) => {
   if (incompleteNotes.length) out.push(`WARNING: scan incomplete; ${incompleteNotes.length} coverage-loss note(s) recorded`)
   for (const item of schedule.items) {
     const safeUntil = item.safe_until ? `  [safe until ${item.safe_until}]` : ''
-    out.push(humanFinding(item.status, `${marker(item.status)} ${item.shutdown ? shutdownText(item) : 'TBD'}  ${item.file}:${item.line}  ${item.matched}  ${findingTail(item, days)}  [${item.usage}]${safeUntil}`))
+    out.push(humanFinding(item, `${marker(item.status)} ${item.shutdown ? shutdownText(item) : 'TBD'}  ${item.file}:${item.line}  ${item.matched}  ${findingTail(item, days)}  [${item.usage}]${safeUntil}`))
   }
   if (schedule.unresolved_integrations.length) {
     out.push('\nUnresolved cloud/gateway references')
@@ -279,6 +299,7 @@ export const formatInventoryCycloneDX = inventory => {
         identity,
         item,
         status: item.status,
+        occurrenceWaivers: new Map(),
         usages: new Set(),
         occurrences: new Set(),
       }
@@ -287,12 +308,54 @@ export const formatInventoryCycloneDX = inventory => {
     if ((statusSeverity.get(item.status) ?? 9) < (statusSeverity.get(group.status) ?? 9)) {
       group.status = item.status
     }
+    const location = `${item.file}#${item.line}`
+    const occurrenceWaiver = group.occurrenceWaivers.get(location) ?? { active: true, activeWaivers: [], expiredWaivers: [] }
+    if (item.waiver?.active === true) occurrenceWaiver.activeWaivers.push(item.waiver)
+    else {
+      occurrenceWaiver.active = false
+      if (item.waiver?.active === false) occurrenceWaiver.expiredWaivers.push(item.waiver)
+    }
+    group.occurrenceWaivers.set(location, occurrenceWaiver)
     group.usages.add(item.usage)
-    group.occurrences.add(`${item.file}#${item.line}`)
+    group.occurrences.add(location)
   }
 
   const components = [...groups.values()].map(group => {
     const { item, identity } = group
+    const occurrenceWaivers = [...group.occurrenceWaivers.values()]
+    const activeWaivers = occurrenceWaivers.flatMap(occurrence => occurrence.activeWaivers)
+    const expiredWaivers = occurrenceWaivers.flatMap(occurrence => occurrence.expiredWaivers)
+    const everyOccurrenceWaived = occurrenceWaivers.every(occurrence => occurrence.active && occurrence.activeWaivers.length > 0)
+    let waiverProperties = []
+    if (activeWaivers.length > 0 && !everyOccurrenceWaived) {
+      waiverProperties = [{ name: 'model-eol:waiver_active', value: 'partial' }]
+    } else if (everyOccurrenceWaived) {
+      const earliestExpiry = activeWaivers.map(waiver => waiver.expires).sort()[0]
+      const distinctWaivers = new Set(activeWaivers.map(waiver => JSON.stringify([waiver.owner, waiver.expires, waiver.reason])))
+      waiverProperties = [
+        { name: 'model-eol:waiver_active', value: 'true' },
+        ...(distinctWaivers.size === 1
+          ? [
+              { name: 'model-eol:waiver_owner', value: activeWaivers[0].owner },
+              { name: 'model-eol:waiver_expires', value: earliestExpiry },
+              { name: 'model-eol:waiver_reason', value: activeWaivers[0].reason },
+            ]
+          : [{ name: 'model-eol:waiver_expires', value: earliestExpiry }]),
+      ]
+    } else if (expiredWaivers.length > 0) {
+      const latestExpiry = expiredWaivers.map(waiver => waiver.expires).sort().at(-1)
+      const distinctWaivers = new Set(expiredWaivers.map(waiver => JSON.stringify([waiver.owner, waiver.expires, waiver.reason])))
+      waiverProperties = [
+        { name: 'model-eol:waiver_active', value: 'false' },
+        ...(distinctWaivers.size === 1
+          ? [
+              { name: 'model-eol:waiver_owner', value: expiredWaivers[0].owner },
+              { name: 'model-eol:waiver_expires', value: latestExpiry },
+              { name: 'model-eol:waiver_reason', value: expiredWaivers[0].reason },
+            ]
+          : [{ name: 'model-eol:waiver_expires', value: latestExpiry }]),
+      ]
+    }
     return {
       type: 'machine-learning-model',
       'bom-ref': identity.bomRef,
@@ -319,6 +382,7 @@ export const formatInventoryCycloneDX = inventory => {
         ...(item.replacement_note
           ? [{ name: 'model-eol:replacement_note', value: item.replacement_note }]
           : []),
+        ...waiverProperties,
         { name: 'model-eol:usage', value: [...group.usages].sort().join(',') },
       ],
       evidence: {

package/lib/scanner.mjs

@@ -638,6 +638,7 @@ export const scanTargets = ({
 
   const pushModelRef = ({ file, line, lineText, matchIndex = null, matched, record, classification, route = null, mappedFrom = null }) => {
     if (ignoresModel(file, matched, record.entry.id) || (mappedFrom && ignoresModel(file, mappedFrom, record.entry.id))) return
+    const waivers = policyForFile?.(path.resolve(file))?.waivers ?? []
     const occurrence = [...lineText.matchAll(new RegExp(escapeRegExp(matched), 'g'))]
       .findIndex(match => match.index === (matchIndex ?? lineText.indexOf(matched)))
     modelRefs.push({
@@ -659,6 +660,7 @@ export const scanTargets = ({
       occurrence: occurrence < 0 ? 0 : occurrence,
       route_index: route?.index ?? null,
       mapped_from: mappedFrom,
+      waivers,
     })
   }
 

package/lib/validate-document.mjs

@@ -64,7 +64,7 @@ export const normalizeDocumentType = value => {
 const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value)
 
 const configKeys = new Set([
-  'days', 'scope', 'via', 'feeds', 'ignore', 'overrides', 'routes', 'issues', 'eval',
+  'days', 'scope', 'via', 'feeds', 'ignore', 'waivers', 'overrides', 'routes', 'issues', 'eval',
 ])
 
 export const detectDocumentType = (document, { file = null } = {}) => {