model-eol 0.2.4 → 0.4.0

package/lib/config.mjs

@@ -0,0 +1,258 @@
+import fs from 'node:fs'
+
+import { matchesAnyGlob, normalizeRepoPath } from './glob.mjs'
+import { MAX_REPORT_BYTES, MAX_TIMEOUT_MS, MIN_TIMEOUT_MS } from './validate-feed.mjs'
+
+const frozenArray = () => Object.freeze([])
+
+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() }),
+  overrides: frozenArray(),
+  routes: frozenArray(),
+  issues: Object.freeze({ enabled: true }),
+  eval: Object.freeze({ command: null, timeout_ms: 600000, max_report_bytes: 65536, pass_env: frozenArray() }),
+})
+
+export const CLI_DEFAULT_CONFIG = Object.freeze({
+  ...DEFAULT_CONFIG,
+  scope: 'all',
+})
+
+const copyDefaults = defaults => ({
+  days: defaults.days,
+  scope: defaults.scope,
+  via: defaults.via,
+  feeds: { allow_vendored_fallback: defaults.feeds.allow_vendored_fallback },
+  ignore: {
+    models: [...defaults.ignore.models],
+    paths: [...defaults.ignore.paths],
+  },
+  overrides: (defaults.overrides ?? []).map(override => ({
+    ...override,
+    paths: [...override.paths],
+    ...(override.ignore ? { ignore: {
+      models: [...(override.ignore.models ?? [])],
+      paths: [...(override.ignore.paths ?? [])],
+    } } : {}),
+  })),
+  routes: (defaults.routes ?? []).map(route => ({ ...route, paths: [...route.paths] })),
+  issues: { enabled: defaults.issues.enabled },
+  eval: {
+    command: defaults.eval.command,
+    timeout_ms: defaults.eval.timeout_ms,
+    max_report_bytes: defaults.eval.max_report_bytes,
+    pass_env: [...defaults.eval.pass_env],
+  },
+})
+
+const assert = (condition, message) => {
+  if (!condition) throw new Error(`invalid .model-eol.json: ${message}`)
+}
+
+const assertKnownKeys = (value, label, allowed) => {
+  for (const key of Object.keys(value)) {
+    const fullKey = label ? `${label}.${key}` : key
+    assert(allowed.has(key), `unknown key "${fullKey}"`)
+  }
+}
+
+const stringArray = (value, label) => {
+  assert(Array.isArray(value), `${label} must be an array`)
+  assert(value.every(item => typeof item === 'string' && item.length > 0), `${label} must contain non-empty strings`)
+  return value.slice()
+}
+
+const nonEmptyString = (value, label) => {
+  assert(typeof value === 'string' && value.length > 0, `${label} must be a non-empty string`)
+  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']))
+  return {
+    models: raw.models === undefined ? [] : stringArray(raw.models, `${label}.models`),
+    paths: raw.paths === undefined ? [] : stringArray(raw.paths, `${label}.paths`),
+  }
+}
+
+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']))
+  const override = { paths: stringArray(raw.paths, `${label}.paths`) }
+  assert(override.paths.length > 0, `${label}.paths must not be empty`)
+  if (raw.days !== undefined) {
+    assert(Number.isInteger(raw.days) && raw.days >= 0, `${label}.days must be a non-negative integer`)
+    override.days = raw.days
+  }
+  if (raw.scope !== undefined) {
+    assert(raw.scope === 'all' || raw.scope === 'direct', `${label}.scope must be all or direct`)
+    override.scope = raw.scope
+  }
+  if (raw.via !== undefined) {
+    assert(raw.via === null || (typeof raw.via === 'string' && raw.via.length > 0), `${label}.via must be null or a non-empty string`)
+    override.via = raw.via
+  }
+  if (raw.ignore !== undefined) override.ignore = normalizeIgnore(raw.ignore, `${label}.ignore`)
+  return override
+}
+
+const normalizeRoute = (raw, index) => {
+  const label = `routes[${index}]`
+  assert(raw && typeof raw === 'object' && !Array.isArray(raw), `${label} must be an object`)
+  assertKnownKeys(raw, label, new Set(['paths', 'via', 'match', 'model']))
+  const route = {
+    paths: stringArray(raw.paths, `${label}.paths`),
+    via: nonEmptyString(raw.via, `${label}.via`),
+  }
+  assert(route.paths.length > 0, `${label}.paths must not be empty`)
+  assert((raw.match === undefined) === (raw.model === undefined), `${label}.match and ${label}.model must be provided together`)
+  if (raw.match !== undefined) {
+    route.match = nonEmptyString(raw.match, `${label}.match`)
+    route.model = nonEmptyString(raw.model, `${label}.model`)
+  }
+  return route
+}
+
+const CREDENTIAL_ENV_PATTERN = /^(?:GITHUB_|GH_|ACTIONS_|SSH_|AWS_SECRET)|(?:TOKEN|SECRET|PASSWORD|CREDENTIAL)/i
+
+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']))
+  const config = copyDefaults(defaults)
+
+  if (raw.days !== undefined) {
+    assert(Number.isInteger(raw.days) && raw.days >= 0, 'days must be a non-negative integer')
+    config.days = raw.days
+  }
+  if (raw.scope !== undefined) {
+    assert(raw.scope === 'all' || raw.scope === 'direct', 'scope must be all or direct')
+    config.scope = raw.scope
+  }
+  if (raw.via !== undefined) {
+    assert(raw.via === null || (typeof raw.via === 'string' && raw.via.length > 0), 'via must be null or a non-empty string')
+    config.via = raw.via
+  }
+  if (raw.feeds !== undefined) {
+    assert(raw.feeds && typeof raw.feeds === 'object' && !Array.isArray(raw.feeds), 'feeds must be an object')
+    assertKnownKeys(raw.feeds, 'feeds', new Set(['allow_vendored_fallback']))
+    if (raw.feeds.allow_vendored_fallback !== undefined) {
+      assert(typeof raw.feeds.allow_vendored_fallback === 'boolean', 'feeds.allow_vendored_fallback must be boolean')
+      config.feeds.allow_vendored_fallback = raw.feeds.allow_vendored_fallback
+    }
+  }
+  if (raw.ignore !== undefined) {
+    const ignore = normalizeIgnore(raw.ignore, 'ignore')
+    if (raw.ignore.models !== undefined) config.ignore.models = ignore.models
+    if (raw.ignore.paths !== undefined) config.ignore.paths = ignore.paths
+  }
+  if (raw.overrides !== undefined) {
+    assert(Array.isArray(raw.overrides), 'overrides must be an array')
+    config.overrides = raw.overrides.map(normalizeOverride)
+  }
+  if (raw.routes !== undefined) {
+    assert(Array.isArray(raw.routes), 'routes must be an array')
+    config.routes = raw.routes.map(normalizeRoute)
+  }
+  if (raw.issues !== undefined) {
+    assert(raw.issues && typeof raw.issues === 'object' && !Array.isArray(raw.issues), 'issues must be an object')
+    assertKnownKeys(raw.issues, 'issues', new Set(['enabled']))
+    if (raw.issues.enabled !== undefined) assert(typeof raw.issues.enabled === 'boolean', 'issues.enabled must be boolean')
+    if (raw.issues.enabled !== undefined) config.issues.enabled = raw.issues.enabled
+  }
+  if (raw.eval !== undefined) {
+    assert(raw.eval && typeof raw.eval === 'object' && !Array.isArray(raw.eval), 'eval must be an object')
+    assertKnownKeys(raw.eval, 'eval', new Set(['command', 'timeout_ms', 'max_report_bytes', 'pass_env']))
+    if (raw.eval.command !== undefined) {
+      assert(raw.eval.command === null || (typeof raw.eval.command === 'string' && raw.eval.command.length > 0), 'eval.command must be null or a non-empty string')
+      config.eval.command = raw.eval.command
+    }
+    if (raw.eval.timeout_ms !== undefined) {
+      assert(Number.isSafeInteger(raw.eval.timeout_ms) && raw.eval.timeout_ms >= MIN_TIMEOUT_MS && raw.eval.timeout_ms <= MAX_TIMEOUT_MS, `eval.timeout_ms must be a safe integer between ${MIN_TIMEOUT_MS} and ${MAX_TIMEOUT_MS}`)
+      config.eval.timeout_ms = raw.eval.timeout_ms
+    }
+    if (raw.eval.max_report_bytes !== undefined) {
+      assert(Number.isSafeInteger(raw.eval.max_report_bytes) && raw.eval.max_report_bytes > 0 && raw.eval.max_report_bytes <= MAX_REPORT_BYTES, `eval.max_report_bytes must be a safe positive integer <= ${MAX_REPORT_BYTES}`)
+      config.eval.max_report_bytes = raw.eval.max_report_bytes
+    }
+    if (raw.eval.pass_env !== undefined) {
+      const passEnv = stringArray(raw.eval.pass_env, 'eval.pass_env')
+      for (const name of passEnv) assert(!CREDENTIAL_ENV_PATTERN.test(name), `eval.pass_env variable "${name}" is not allowed`)
+      config.eval.pass_env = passEnv
+    }
+  }
+
+  return config
+}
+
+export const configForRepoPath = (config, repoPath) => {
+  const normalizedPath = normalizeRepoPath(repoPath)
+  const policy = {
+    days: config.days,
+    scope: config.scope,
+    via: config.via,
+    ignore: {
+      models: [...config.ignore.models],
+      paths: [...config.ignore.paths],
+    },
+    override_indexes: [],
+  }
+  for (const [index, override] of (config.overrides ?? []).entries()) {
+    if (!matchesAnyGlob(normalizedPath, override.paths)) continue
+    policy.override_indexes.push(index)
+    if (override.days !== undefined) policy.days = override.days
+    if (override.scope !== undefined) policy.scope = override.scope
+    if (override.via !== undefined) policy.via = override.via
+    if (override.ignore) {
+      policy.ignore.models.push(...override.ignore.models)
+      policy.ignore.paths.push(...override.ignore.paths)
+    }
+  }
+  policy.ignore.models = [...new Set(policy.ignore.models)]
+  policy.ignore.paths = [...new Set(policy.ignore.paths)]
+  return policy
+}
+
+export const routeForRepoReference = (config, repoPath, { matched = null, id = null } = {}) => {
+  const normalizedPath = normalizeRepoPath(repoPath)
+  let selected = null
+  for (const [index, route] of (config.routes ?? []).entries()) {
+    if (!matchesAnyGlob(normalizedPath, route.paths)) continue
+    if (route.match !== undefined && route.match !== matched && route.match !== id) continue
+    selected = { ...route, index }
+  }
+  return selected
+}
+
+export const mappedRoutesForRepoPath = (config, repoPath) => {
+  const normalizedPath = normalizeRepoPath(repoPath)
+  return (config.routes ?? []).flatMap((route, index) =>
+    route.match !== undefined && route.model !== undefined && matchesAnyGlob(normalizedPath, route.paths)
+      ? [{ ...route, index }]
+      : [])
+}
+
+export const configuredVias = config => [
+  config.via,
+  ...(config.overrides ?? []).map(override => override.via),
+  ...(config.routes ?? []).map(route => route.via),
+].filter(via => typeof via === 'string' && via.length > 0)
+
+export const loadConfig = (file, { defaults = DEFAULT_CONFIG, allowMissing = true } = {}) => {
+  if (!fs.existsSync(file)) {
+    if (allowMissing) return normalizeConfig({}, { defaults })
+    throw new Error(`could not read config ${file}: file not found`)
+  }
+  let value
+  try {
+    value = JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch (error) {
+    throw new Error(`could not read config ${file}: ${error.message}`)
+  }
+  return normalizeConfig(value, { defaults })
+}

package/lib/feeds.mjs

@@ -5,12 +5,23 @@ import { assertIsoDate, assertValidFeed } from './validate-feed.mjs'
 
 export { assertIsoDate }
 
+export const BUILTIN_CHANNELS = Object.freeze([
+  'azure-ai-foundry',
+  'aws-bedrock',
+  'vertex-ai',
+  'openrouter',
+  'litellm',
+  'portkey',
+  'ai-gateway',
+])
+
 export const esc = s => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 
 export const loadFeeds = feedsDir => {
   const feeds = []
   const entries = new Map()
   const keyFiles = new Map()
+  const vias = new Set()
 
   for (const f of fs.readdirSync(feedsDir).filter(f => f.endsWith('.json'))) {
     const file = path.join(feedsDir, f)
@@ -22,6 +33,7 @@ export const loadFeeds = feedsDir => {
     assertValidFeed(feed, file)
     feeds.push({ ...feed, file })
     for (const m of feed.models ?? []) {
+      for (const distribution of m.distributions ?? []) vias.add(distribution.via)
       const record = {
         entry: m,
         publisher: feed.publisher,
@@ -45,6 +57,7 @@ export const loadFeeds = feedsDir => {
     feeds,
     entries,
     keys: [...entries.keys()].sort((a, b) => b.length - a.length),
+    vias: [...vias].sort(),
   }
 }
 
@@ -71,13 +84,18 @@ const policySafeUntil = (policy, generated) => {
 export const effectiveShutdown = (entry, via) => {
   if (via) {
     const d = (entry.distributions ?? []).find(d => d.via === via)
-    if (d) return { date: d.shutdown ?? null, via, date_precision: d.date_precision ?? null }
+    if (d) return {
+      date: d.shutdown ?? null,
+      via,
+      date_precision: d.date_precision ?? null,
+      distribution_status: d.status ?? null,
+    }
     if (entry.shutdown || entry.announced) {
-      return { date: entry.shutdown ?? null, via: 'publisher-fallback', date_precision: entry.date_precision ?? null }
+      return { date: entry.shutdown ?? null, via: 'publisher-fallback', date_precision: entry.date_precision ?? null, distribution_status: null }
     }
     return null
   }
-  return entry.shutdown ? { date: entry.shutdown, via: 'publisher', date_precision: entry.date_precision ?? null } : null
+  return entry.shutdown ? { date: entry.shutdown, via: 'publisher', date_precision: entry.date_precision ?? null, distribution_status: null } : null
 }
 
 export const lifecycleFor = (entry, options) => {
@@ -90,12 +108,24 @@ export const lifecycleFor = (entry, options) => {
   } = options
   const sd = effectiveShutdown(entry, via)
   if (sd) {
+    if (sd.distribution_status === 'retired') {
+      return {
+        status: 'retired',
+        shutdown: sd.date,
+        date_precision: sd.date_precision,
+        distribution_status: sd.distribution_status,
+        via: sd.via,
+        days: sd.date ? daysUntil(sd.date, today) : null,
+        safe_until: sd.date,
+      }
+    }
     if (sd.date) {
       const remaining = daysUntil(sd.date, today)
       return {
         status: remaining < 0 ? 'retired' : remaining <= days ? 'retiring' : 'scheduled',
         shutdown: sd.date,
         date_precision: sd.date_precision,
+        distribution_status: sd.distribution_status,
         via: sd.via,
         days: remaining,
         safe_until: sd.date,
@@ -110,6 +140,7 @@ export const lifecycleFor = (entry, options) => {
       status,
       shutdown: null,
       date_precision: sd.date_precision,
+      distribution_status: sd.distribution_status,
       via: sd.via,
       days: null,
       safe_until: status === 'ok' && !entry.announced && !entry.shutdown
@@ -118,12 +149,13 @@ export const lifecycleFor = (entry, options) => {
     }
   }
   if (entry.announced) {
-    return { status: 'watch', shutdown: null, date_precision: null, via: null, days: null, safe_until: null }
+    return { status: 'watch', shutdown: null, date_precision: null, distribution_status: null, via: null, days: null, safe_until: null }
   }
   return {
     status: 'ok',
     shutdown: null,
     date_precision: null,
+    distribution_status: null,
     via: null,
     days: null,
     safe_until: policySafeUntil(policy, generated),
@@ -157,12 +189,14 @@ export const findingFromRef = (ref, options) => {
     status: lifecycle.status,
     shutdown: lifecycle.shutdown,
     date_precision: lifecycle.date_precision ?? null,
+    distribution_status: lifecycle.distribution_status ?? null,
     via: lifecycle.via,
     days: lifecycle.days,
     safe_until: lifecycle.safe_until,
     replacement: ref.entry.replacement ?? null,
     replacement_options: ref.entry.replacement_options ?? null,
     replacement_note: ref.entry.replacement_note ?? null,
+    threshold_days: days,
   }
 }
 

package/lib/glob.mjs

@@ -0,0 +1,35 @@
+const escapeRegExp = value => value.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+
+export const normalizeRepoPath = value => String(value ?? '')
+  .replaceAll('\\', '/')
+  .replace(/^\.\//, '')
+  .replace(/^\/+/, '')
+
+export const globRegex = pattern => {
+  let source = ''
+  const value = normalizeRepoPath(pattern)
+  for (let i = 0; i < value.length; i++) {
+    const char = value[i]
+    if (char === '*' && value[i + 1] === '*') {
+      if (value[i + 2] === '/') {
+        source += '(?:.*/)?'
+        i += 2
+      } else {
+        source += '.*'
+        i++
+      }
+    } else if (char === '*') {
+      source += '[^/]*'
+    } else if (char === '?') {
+      source += '[^/]'
+    } else {
+      source += escapeRegExp(char)
+    }
+  }
+  return new RegExp(`^${source}$`)
+}
+
+export const matchesGlob = (file, pattern) => globRegex(pattern).test(normalizeRepoPath(file))
+
+export const matchesAnyGlob = (file, patterns = []) =>
+  patterns.some(pattern => matchesGlob(file, pattern))

package/lib/plan.mjs

@@ -22,6 +22,10 @@ const readLines = (file, cache) => {
 
 const notesFor = ref => [ref.feedNote, ref.entry.notes].filter(Boolean).join(' - ') || null
 
+const requestedVia = (finding, fallback) => Object.hasOwn(finding, 'requested_via')
+  ? finding.requested_via
+  : fallback
+
 const issueFor = (ref, finding, reason, via) => ({
   file: ref.file,
   line: ref.line,
@@ -33,6 +37,11 @@ const issueFor = (ref, finding, reason, via) => ({
   status: finding.status,
   shutdown: finding.shutdown,
   via: finding.via,
+  requested_via: requestedVia(finding, via),
+  threshold_days: finding.threshold_days,
+  effective_scope: finding.effective_scope,
+  ...(finding.policy_provenance ? { policy_provenance: finding.policy_provenance } : {}),
+  ...(ref.mapped_from ? { mapped_from: ref.mapped_from } : {}),
   days: finding.days,
   replacement: finding.replacement,
   ...(finding.replacement_options?.length ? { replacement_options: finding.replacement_options } : {}),
@@ -42,8 +51,8 @@ const issueFor = (ref, finding, reason, via) => ({
   notes: notesFor(ref),
 })
 
-const scopeIncludes = (ref, scope) =>
-  scope !== 'direct' || ref.usage === 'direct-api' || ref.usage === 'model-reference'
+const scopeIncludes = (ref, scope, finding = null) =>
+  (finding?.effective_scope ?? scope) !== 'direct' || ref.usage === 'direct-api' || ref.usage === 'model-reference'
 
 const occurrenceInLine = (line, matched, index) => {
   let occurrence = 0
@@ -62,13 +71,16 @@ export const buildPlan = ({ scan, findings, entries, days, via, scope }) => {
   const lineCache = new Map()
 
   scan.modelRefs.forEach((ref, index) => {
-    if (!scopeIncludes(ref, scope)) return
     const finding = findings[index]
+    if (!scopeIncludes(ref, scope, finding)) return
     if (!finding || finding.status === 'ok') return
+    const effectiveVia = requestedVia(finding, via)
+    const effectiveDays = finding.threshold_days ?? days
 
     let reason
     if (finding.status === 'watch') reason = 'watch'
     else if (finding.status !== 'retired' && finding.status !== 'retiring') reason = 'outside-threshold'
+    else if (!finding.shutdown) reason = 'shutdown-date-unavailable'
     else if (finding.via === 'publisher-fallback') reason = 'publisher-fallback'
     else if (ref.usage !== 'direct-api' || ref.confidence !== 'high') reason = 'not-direct-api'
     else if (!finding.replacement && finding.replacement_options?.length) reason = 'replacement-choice'
@@ -77,7 +89,7 @@ export const buildPlan = ({ scan, findings, entries, days, via, scope }) => {
       const replacementRecord = entries.get(finding.replacement)
       if (!replacementRecord || replacementRecord.publisher !== finding.publisher) reason = 'replacement-unresolved'
       else {
-        const replacementLifecycle = lifecycleFor(replacementRecord.entry, { days, via })
+        const replacementLifecycle = lifecycleFor(replacementRecord.entry, { days: effectiveDays, via: effectiveVia })
         if (isBad(replacementLifecycle)) reason = 'replacement-retiring'
       }
     }
@@ -92,7 +104,7 @@ export const buildPlan = ({ scan, findings, entries, days, via, scope }) => {
     if (line === undefined) reason = reason ?? 'line-unavailable'
 
     if (reason) {
-      issues.push(issueFor(ref, finding, reason, via))
+      issues.push(issueFor(ref, finding, reason, effectiveVia))
       return
     }
 
@@ -100,7 +112,7 @@ export const buildPlan = ({ scan, findings, entries, days, via, scope }) => {
       ? ref.occurrence
       : occurrenceInLine(line, ref.matched, line.indexOf(ref.matched))
     if (line.indexOf(ref.matched) === -1) {
-      issues.push(issueFor(ref, finding, 'match-unavailable', via))
+      issues.push(issueFor(ref, finding, 'match-unavailable', effectiveVia))
       return
     }
 
@@ -116,19 +128,26 @@ export const buildPlan = ({ scan, findings, entries, days, via, scope }) => {
       shutdown: finding.shutdown,
       days: finding.days,
       status: finding.status,
-      sources: sourceList(ref, finding, via),
+      requested_via: effectiveVia,
+      threshold_days: effectiveDays,
+      effective_scope: finding.effective_scope ?? scope,
+      ...(finding.policy_provenance ? { policy_provenance: finding.policy_provenance } : {}),
+      ...(ref.mapped_from ? { mapped_from: ref.mapped_from } : {}),
+      sources: sourceList(ref, finding, effectiveVia),
       notes: notesFor(ref),
     })
   })
 
   for (const candidate of scan.candidateRefs) {
-    if (scope === 'direct' && candidate.usage !== 'direct-api' && candidate.usage !== 'model-reference') continue
+    if ((candidate.effective_scope ?? scope) === 'direct' && candidate.usage !== 'direct-api' && candidate.usage !== 'model-reference') continue
     issues.push({
       file: candidate.file,
       line: candidate.line,
       matched: candidate.matched,
       usage: candidate.usage,
       confidence: candidate.confidence,
+      effective_scope: candidate.effective_scope ?? scope,
+      ...(candidate.policy_provenance ? { policy_provenance: candidate.policy_provenance } : {}),
       reason: 'candidate',
       notes: candidate.reason,
     })

package/lib/reports.mjs

@@ -1,5 +1,6 @@
 import { isBad } from './feeds.mjs'
 import { color } from './color.mjs'
+import { incompleteScanNotes } from './scanner.mjs'
 
 export const marker = status =>
   status === 'retired' ? '✗' :
@@ -18,9 +19,10 @@ const replacementTail = finding => finding.replacement
     : ''
 
 export const findingTail = (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)}` :
-  f.status === 'scheduled' ? `scheduled ${shutdownText(f)} (${f.days} days, outside --days ${days})` :
+  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'
 
@@ -53,8 +55,14 @@ export const buildInventory = ({ scan, findings, days, via, scope, targets }) =>
       status: lifecycle.status,
       shutdown: lifecycle.shutdown,
       date_precision: lifecycle.date_precision,
+      distribution_status: lifecycle.distribution_status,
       via: lifecycle.via,
+      requested_via: lifecycle.requested_via,
       days: lifecycle.days,
+      threshold_days: lifecycle.threshold_days,
+      effective_scope: lifecycle.effective_scope,
+      ...(lifecycle.policy_provenance ? { policy_provenance: lifecycle.policy_provenance } : {}),
+      ...(ref.mapped_from ? { mapped_from: ref.mapped_from } : {}),
       safe_until: lifecycle.safe_until,
       replacement: lifecycle.replacement,
       source: ref.source,
@@ -87,7 +95,7 @@ export const buildInventory = ({ scan, findings, days, via, scope, targets }) =>
 export const buildSchedule = inventory => {
   const severity = { retired: 0, retiring: 1, scheduled: 2, watch: 3, ok: 4 }
   const inScope = item =>
-    inventory.scope !== 'direct' || item.usage === 'direct-api' || item.usage === 'model-reference'
+    (item.effective_scope ?? inventory.scope) !== 'direct' || item.usage === 'direct-api' || item.usage === 'model-reference'
   const items = inventory.model_references
     .filter(item => item.status !== 'ok')
     .filter(inScope)
@@ -172,7 +180,8 @@ export const formatCheck = ({ findings, bad, scannedFiles, days, scope }) => {
 
 export const formatInventory = (inventory, days) => {
   const out = [color('bold', `model-eol inventory: ${inventory.summary.model_references} tracked model reference(s), ${inventory.summary.candidate_model_references} candidate(s), ${inventory.summary.integration_hints} integration hint(s) across ${inventory.scanned_files} files`)]
-  if ((inventory.scan_notes ?? []).length) out.push(`WARNING: scan incomplete; ${inventory.scan_notes.length} scan note(s) recorded`)
+  const incompleteNotes = incompleteScanNotes(inventory.scan_notes ?? [])
+  if (incompleteNotes.length) out.push(`WARNING: scan incomplete; ${incompleteNotes.length} coverage-loss note(s) recorded`)
   if (inventory.model_references.length) {
     out.push('\nModel references')
     for (const item of inventory.model_references) {
@@ -197,7 +206,8 @@ export const formatInventory = (inventory, days) => {
 
 export const formatSchedule = (schedule, days) => {
   const out = [color('bold', `model-eol schedule: ${schedule.items.length} scheduled/watch finding(s), ${schedule.candidate_model_references.length} candidate(s), ${schedule.unresolved_integrations.length} unresolved cloud/gateway hint(s)`)]
-  if ((schedule.scan_notes ?? []).length) out.push(`WARNING: scan incomplete; ${schedule.scan_notes.length} scan note(s) recorded`)
+  const incompleteNotes = incompleteScanNotes(schedule.scan_notes ?? [])
+  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}`))
@@ -247,7 +257,12 @@ export const formatInventoryCycloneDX = inventory => {
     bomFormat: 'CycloneDX',
     specVersion: '1.6',
     version: 1,
-    metadata: { timestamp: inventory.generated },
+    metadata: {
+      timestamp: inventory.generated,
+      properties: [
+        { name: 'model-eol:generator', value: 'model-eol/inventory-cyclonedx@0.1' },
+      ],
+    },
     components: [...components.values()],
   }
 }
@@ -261,7 +276,8 @@ const annotationEscape = value => String(value)
 
 export const formatAlertGithub = (alert, days) => {
   const out = []
-  if ((alert.scan_notes ?? []).length) out.push(`::warning title=${annotationEscape('model-eol scan')}::${annotationEscape(`Scan incomplete; ${alert.scan_notes.length} scan note(s) recorded`)}`)
+  const incompleteNotes = incompleteScanNotes(alert.scan_notes ?? [])
+  if (incompleteNotes.length) out.push(`::warning title=${annotationEscape('model-eol scan')}::${annotationEscape(`Scan incomplete; ${incompleteNotes.length} coverage-loss note(s) recorded`)}`)
   for (const item of alert.errors) {
     const title = `model-eol ${item.status}: ${item.matched}`
     out.push(`::error file=${annotationEscape(item.file)},line=${item.line},title=${annotationEscape(title)}::${annotationEscape(findingTail(item, days))}`)
@@ -283,7 +299,8 @@ export const formatAlertGithub = (alert, days) => {
 
 export const formatAlertMarkdown = (alert, days) => {
   const out = ['# model-eol alert', '']
-  if ((alert.scan_notes ?? []).length) out.push(`> Warning: scan incomplete; ${alert.scan_notes.length} scan note(s) recorded.`, '')
+  const incompleteNotes = incompleteScanNotes(alert.scan_notes ?? [])
+  if (incompleteNotes.length) out.push(`> Warning: scan incomplete; ${incompleteNotes.length} coverage-loss note(s) recorded.`, '')
   out.push(`- Errors: ${alert.errors.length}`)
   out.push(`- Warnings: ${alert.warnings.length}`)
   if (alert.errors.length) {