model-eol 0.5.1 → 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/feeds/google.json

@@ -1,7 +1,7 @@
 {
   "spec": "model-eol/0.1",
   "publisher": "google",
-  "generated": "2026-08-18T00:47:44.931Z",
+  "generated": "2026-08-31T05:30:20.090Z",
   "source": "https://ai.google.dev/gemini-api/docs/deprecations",
   "models": [
     {
@@ -574,7 +574,11 @@
       ]
     },
     {
-      "id": "gemini-omni-flash-preview"
+      "id": "gemini-omni-flash-preview",
+      "source": "https://ai.google.dev/gemini-api/docs/deprecations",
+      "shutdown": "2026-09-30",
+      "date_precision": "earliest",
+      "replacement": "gemini-omni-1.1-flash"
     },
     {
       "id": "gemini-robotics-er-2-preview"
@@ -610,7 +614,20 @@
       "id": "gemini-robotics-er-2-streaming-preview"
     },
     {
-      "id": "gemini-3.5-live-translate-preview"
+      "id": "gemini-3.5-live-translate-preview",
+      "source": "https://ai.google.dev/gemini-api/docs/deprecations"
+    },
+    {
+      "id": "gemini-3.5-transcribe-live",
+      "source": "https://ai.google.dev/gemini-api/docs/deprecations"
+    },
+    {
+      "id": "gemini-3.5-transcribe",
+      "source": "https://ai.google.dev/gemini-api/docs/deprecations"
+    },
+    {
+      "id": "gemini-omni-1.1-flash",
+      "source": "https://ai.google.dev/gemini-api/docs/deprecations"
     }
   ]
 }

package/feeds/openai.json

@@ -1,7 +1,7 @@
 {
   "spec": "model-eol/0.1",
   "publisher": "openai",
-  "generated": "2026-08-18T00:47:44.930Z",
+  "generated": "2026-08-31T05:30:19.216Z",
   "source": "https://developers.openai.com/api/docs/deprecations",
   "note": "Community-maintained seed dataset, compiled 2026-07-25 from the provider's deprecations page. Verify against the source before acting; this file demonstrates the format.",
   "models": [
@@ -937,7 +937,14 @@
       "id": "text-embedding-ada-002"
     },
     {
-      "id": "whisper-1"
+      "id": "whisper-1",
+      "announced": "2026-08-26",
+      "shutdown": "2027-02-26",
+      "source": "https://developers.openai.com/api/docs/deprecations",
+      "replacement_options": [
+        "gpt-live-transcribe",
+        "gpt-transcribe"
+      ]
     },
     {
       "id": "tts-1"
@@ -988,10 +995,24 @@
       "id": "gpt-4o-mini-search-preview"
     },
     {
-      "id": "gpt-4o-transcribe"
+      "id": "gpt-4o-transcribe",
+      "announced": "2026-08-26",
+      "shutdown": "2027-02-26",
+      "source": "https://developers.openai.com/api/docs/deprecations",
+      "replacement_options": [
+        "gpt-live-transcribe",
+        "gpt-transcribe"
+      ]
     },
     {
-      "id": "gpt-4o-mini-transcribe"
+      "id": "gpt-4o-mini-transcribe",
+      "announced": "2026-08-26",
+      "shutdown": "2027-02-26",
+      "source": "https://developers.openai.com/api/docs/deprecations",
+      "replacement_options": [
+        "gpt-live-transcribe",
+        "gpt-transcribe"
+      ]
     },
     {
       "id": "gpt-4o-mini-tts"
@@ -1009,7 +1030,14 @@
       "id": "gpt-4.1-mini"
     },
     {
-      "id": "gpt-4o-transcribe-diarize"
+      "id": "gpt-4o-transcribe-diarize",
+      "announced": "2026-08-26",
+      "shutdown": "2027-02-26",
+      "source": "https://developers.openai.com/api/docs/deprecations",
+      "replacement_options": [
+        "gpt-live-transcribe",
+        "gpt-transcribe"
+      ]
     },
     {
       "id": "gpt-5"

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),
     })