model-eol 0.8.4 → 0.9.0

package/README.md

@@ -571,6 +571,98 @@ Flash-Lite GA models. The pipeline opened
 and downstream checks stopped warning about dates Google no longer listed. A
 lifecycle tracker has to retract stale alarms as well as add new ones.
 
+## Receipts
+
+model-eol writes three receipt kinds. Each one is a public Draft-07 schema,
+and `model-eol validate receipt.json` selects the schema from the receipt's
+`schema` value.
+
+| Kind | `schema` value | Binds |
+|---|---|---|
+| [Eval results manifest](https://thossullivan.github.io/model-eol/schema/0.1/model-eol.eval.schema.json) | `model-eol.eval/0.1` | One pass, fail, or timeout result per migration group to the evaluated base commit, the plan digest, the eval settings digest, and each group's feed digest. Written by `model-eol-bot evaluate`. |
+| [Feed-refresh receipt](https://thossullivan.github.io/model-eol/schema/0.1/model-eol.feed-refresh-receipt.schema.json) | `model-eol/feed-refresh-receipt@0.1` | The refresh run URL, the checked commit, and the check time to the SHA-256 of every `feeds/*.json` file. A pending receipt also names the open feed PR. |
+| [npm release result](https://thossullivan.github.io/model-eol/schema/0.1/model-eol.npm-release-result.schema.json) | `model-eol/npm-release-result@0.2` | The release workflow's source commit to either no release, or one exact version, its tag, the release commit, and the registry tarball's sha512 integrity. |
+
+Additive changes keep a receipt's version. Any change that makes an old
+receipt invalid, or changes what a digest covers, is a new version. Validators
+reject unknown versions. A few rules, such as feed sort order and `tag` equal
+to `v` plus `version`, cannot be written in Draft-07. Each schema's
+`description` lists them, and `model-eol validate` enforces them in code.
+
+`model-eol validate` checks a receipt's structure only. `model-eol verify`
+checks what a receipt claims against inputs you supply:
+
+```bash
+# release result against the exact tarball you hold (no registry lookup)
+npm pack model-eol@0.8.4
+model-eol verify npm-release-result.json --package model-eol-0.8.4.tgz \
+  --commit RELEASE_SHA --source-commit SOURCE_SHA --version 0.8.4
+
+# refresh receipt against a checkout's feeds directory
+model-eol verify feed-refresh-receipt.json --feeds-dir ./feeds \
+  --commit REFRESH_SHA --run-url https://github.com/OWNER/REPO/actions/runs/ID
+
+# eval manifest against the plan, config, and feeds the evaluator used
+model-eol verify eval-results.json --commit BASE_SHA --plan plan.json \
+  --config .model-eol.json --feeds-dir ./feeds
+```
+
+The receipt kind comes from its `schema` value. verify validates the receipt's
+structure first, then reports each claim. It never reads the current
+directory, git state, or the network; every input is an explicit flag.
+
+| Flag | Checks |
+|---|---|
+| `--feeds-dir DIR` | Refresh: the SHA-256 of every `DIR/*.json`, compared with the receipt's `feeds` list as a set. Changed, missing, and extra files are each a mismatch. `DIR` is the feeds directory itself; a repository root (a directory holding `feeds/`) is refused. Eval: with `--plan` and `--config`, recomputes each result's `feed_digest` (`--plan` and `--config` alone already fix the expected result set). |
+| `--commit SHA` | Refresh `refresh_commit`, release `release_commit`, or eval `base_sha`. |
+| `--run-url URL` | Refresh `refresh_run`, after the same HTTPS URL normalization the receipt writer applies. |
+| `--package FILE.tgz` | Release `registry_integrity`: the sha512 SRI of the tarball bytes. |
+| `--source-commit SHA` | Release `source_commit`. |
+| `--version X.Y.Z` | Release `version`; `tag` is bound to it as `vX.Y.Z`. |
+| `--plan FILE` | Eval `plan_digest`, from a validated `model-eol.plan/0.1` document. |
+| `--config FILE` | Eval `eval_config_digest` and `configured`, with the bot's settings resolution. `MODEL_EOL_EVAL_COMMAND` in the environment overrides `eval.command` as it does for the bot, and the output says so. For a repository without `.model-eol.json`, pass a file containing `{}`. |
+| `--require-all` | Exit 1 when the result is `partial`. |
+| `--json` | Emit a [`model-eol/verification@0.1`](https://thossullivan.github.io/model-eol/schema/0.1/model-eol.verification.schema.json) document. |
+
+SHA inputs are 40 to 64 hex characters; uppercase is lowercased. A flag that
+does not apply to the receipt's kind is a usage error.
+
+Each claim is `verified`, `mismatch` (with the receipt's value and the
+computed one), `not-checked` (with the flag that would check it), or
+`not-applicable` (a `released: false` result makes no release claims, so only
+`source_commit` applies). Supplying `--commit`, `--version`, or `--package` for a
+`released: false` result adds a `released` claim that mismatches, because those
+inputs assert a release the receipt says did not happen. For a refresh receipt,
+the report also shows its `state`, `checked_at`, and `pending_pr` as information;
+a pending receipt verifies by the same rules as a clean one. For a release
+result the report shows `released`; a release gate must pass `--package`,
+`--version`, `--commit`, and `--require-all`, so that a no-release receipt
+mismatches instead of verifying through `--source-commit` alone.
+
+For a configured eval manifest, `--plan` and `--config` fix the set of result
+identities the evaluator had to produce: a planned identity with no result, a
+result for an unplanned identity, and a duplicated identity are each a
+mismatch, and `--feeds-dir` additionally checks each result's `feed_digest`.
+Without `--plan` and `--config`, a `results` claim is reported as not checked,
+so stripping results from a manifest never verifies. Text output escapes
+control characters in every printed value. The overall result is `verified` only when every
+applicable claim is verified. It is `partial` when nothing mismatched but at
+least one claim was not checked: the receipt is consistent with what you
+supplied, not proven. It is `mismatch` when any claim mismatched.
+
+Eval outcomes are never claims. `verify` does not check `status`, `exit_code`,
+`report`, or `generated`, because an evaluation cannot be reproduced offline. A
+`verified` eval manifest is bound to the supplied commit, plan, config, and
+feeds. It does not mean the evals passed. A gate that needs passing evals must
+read the results itself.
+
+| Exit | Meaning |
+|---|---|
+| 0 | No mismatch: `verified`, or `partial` without `--require-all`. |
+| 1 | At least one claim mismatched, or `partial` with `--require-all`. |
+| 2 | Usage error, unreadable file, structurally invalid receipt, or unsupported receipt schema or version. No claim is reported. |
+| 3 | Output write failure when the result would otherwise exit 0. |
+
 ## The actual ask
 
 The goal is the format, not another checker. Providers already publish
@@ -592,7 +684,7 @@ is the most useful thing any of us can do here.
   canonical schemas, feeds, refresh health, a publication manifest, and Atom.
   Each deployment is bound to an exact feed-refresh receipt and verified against
   every live asset. `model-eol validate` checks feeds, repository policy, check
-  reports, inventories, schedules, alerts, and plans against the same
+  reports, inventories, schedules, alerts, plans, and receipts against the same
   zero-dependency runtime contracts.
 - Current-model entries, and therefore policy-floor horizons, populate only when
   the refresh runs with provider API keys for the models endpoints. Anthropic's

package/action.yml

@@ -41,7 +41,7 @@ inputs:
     required: false
     default: ''
   document-type:
-    description: 'Optional validate document type: feed, config, check, inventory, schedule, alert, or plan'
+    description: 'Optional validate document type: feed, config, check, inventory, schedule, alert, plan, eval, feed-refresh-receipt, or npm-release-result'
     required: false
     default: ''
   include-docs:

package/bot/bot.mjs

@@ -12,11 +12,9 @@ import {
   branchFor,
   daysRemaining,
   hasMetadataMarker,
-  itemDigest,
   markdownCode,
   markdownLink,
   markdownText,
-  matchesAnyGlob,
   metadataLine,
   parseMetadata,
   repoPath,
@@ -24,9 +22,22 @@ import {
   staleWorkComment,
   stableJson,
 } from './lib/common.mjs'
+import {
+  contextFor,
+  effectiveEval,
+  evalConfigDigest,
+  evalIdentity,
+  feedContext,
+  groupDigest,
+  ignoredModelIds,
+  isIgnored,
+  modelGroups,
+  planDigest,
+} from '../lib/digests.mjs'
 import { assertValidPlanDocument } from '../lib/validate-document.mjs'
 import { captureWindowFor, lifecycleFor } from '../lib/feeds.mjs'
 import { parseCliArgs } from '../lib/cli.mjs'
+import { EVAL_RESULTS_SCHEMA as EVAL_SCHEMA, assertValidEvalResults } from '../lib/receipts.mjs'
 import { loadConfig } from './lib/config.mjs'
 import { downloadFeeds } from './lib/feeds.mjs'
 import { capReport, readReportCapped, runEvalHook, reportForBody } from './lib/eval.mjs'
@@ -47,12 +58,13 @@ import {
   verifyRemoteBranchHead,
 } from './lib/git.mjs'
 
+export { contextFor }
+
 const ROOT = path.resolve(import.meta.dirname, '..')
 const CHECKER = path.join(ROOT, 'check.mjs')
 const VENDORED_FEEDS = path.join(ROOT, 'feeds')
 const PLAN_SCHEMA = 'model-eol.plan/0.1'
 const BOT_SCHEMA = 'model-eol.bot/0.1'
-const EVAL_SCHEMA = 'model-eol.eval/0.1'
 const EVAL_FAILURE_CHANNEL = 'configured-eval'
 const EVAL_ARTIFACT_MAX_BYTES = 64 * 1024 * 1024
 const ISSUE_REASONS = new Set([
@@ -207,27 +219,6 @@ const verifiedPlanArtifact = (file, generatedPlan) => {
   return artifact
 }
 
-const withoutGenerated = plan => {
-  const { generated, ...stable } = plan
-  return stable
-}
-
-const planDigest = plan => sha256(stableJson(withoutGenerated(plan)))
-
-const effectiveEval = (config, commandOverride = null) => ({
-  ...config.eval,
-  command: typeof commandOverride === 'string' && commandOverride.trim() ? commandOverride : config.eval.command,
-})
-
-const evalConfigDigest = settings => sha256(stableJson({
-  command: settings.command ?? null,
-  timeout_ms: settings.timeout_ms,
-  max_report_bytes: settings.max_report_bytes,
-  pass_env: settings.pass_env,
-}))
-
-const evalIdentity = (publisher, id, via) => `${publisher}\0${id}\0${via ?? ''}`
-
 const readJsonArtifact = (file, maxBytes, label) => {
   const absolute = asAbsolute(file)
   const artifact = readReportCapped(absolute, maxBytes + 1)
@@ -245,30 +236,26 @@ const readEvalResults = ({ file, config, commandOverride, plan, groups, baseHead
   const maxBytes = Math.min(EVAL_ARTIFACT_MAX_BYTES, Math.max(1024 * 1024, groups.length * (settings.max_report_bytes + 2048)))
   const artifact = readJsonArtifact(file, maxBytes, 'eval results artifact')
   if (artifact?.schema !== EVAL_SCHEMA) throw new Error(`refusing eval results schema ${artifact?.schema ?? 'missing'}; expected ${EVAL_SCHEMA}`)
+  try {
+    assertValidEvalResults(artifact)
+  } catch (error) {
+    throw new Error(`refusing eval results artifact: ${error.message}`)
+  }
   if (artifact.plan_digest !== planDigest(plan)) throw new Error('refusing eval results artifact: plan digest does not match the independently verified plan')
   if (artifact.eval_config_digest !== evalConfigDigest(settings)) throw new Error('refusing eval results artifact: eval configuration digest does not match')
-  if (typeof artifact.base_sha !== 'string' || !/^[0-9a-f]{40,64}$/.test(artifact.base_sha)) throw new Error('refusing eval results artifact: evaluated base commit is malformed or missing')
   if (artifact.base_sha !== baseHead) throw new Error(`refusing eval results artifact: evaluated base commit ${artifact.base_sha} does not match current default-branch head ${baseHead}`)
   const configured = Boolean(settings.command)
   if (artifact.configured !== configured) throw new Error('refusing eval results artifact: configured state does not match eval.command')
-  if (!Array.isArray(artifact.results)) throw new Error('refusing eval results artifact: results must be an array')
   if (artifact.results.length !== (configured ? groups.length : 0)) {
     throw new Error('refusing eval results artifact: expected exactly one result for every planned migration')
   }
   const expected = new Map(groups.map(group => [evalIdentity(group.publisher, group.id, group.via), group]))
   const results = new Map()
   for (const result of artifact.results) {
-    if (!result || typeof result !== 'object' || Array.isArray(result)) throw new Error('refusing eval results artifact: result must be an object')
-    if (typeof result.publisher !== 'string' || !result.publisher || typeof result.id !== 'string' || !result.id) throw new Error('refusing eval results artifact: result identity is malformed')
-    if (result.via !== null && typeof result.via !== 'string') throw new Error('refusing eval results artifact: result clock is malformed')
     const key = evalIdentity(result.publisher, result.id, result.via)
     const group = expected.get(key)
     if (!group || results.has(key)) throw new Error('refusing eval results artifact: result identity is unexpected or duplicated')
     if (result.feed_digest !== group.feedDigest) throw new Error(`refusing eval results artifact: feed digest mismatch for ${group.publisher}/${group.id}`)
-    if (!['pass', 'fail', 'timeout'].includes(result.status)) throw new Error(`refusing eval results artifact: invalid status for ${group.publisher}/${group.id}`)
-    if (result.exit_code !== null && !Number.isSafeInteger(result.exit_code)) throw new Error(`refusing eval results artifact: invalid exit code for ${group.publisher}/${group.id}`)
-    if (result.status === 'pass' && result.exit_code !== 0) throw new Error(`refusing eval results artifact: passing result has a non-zero exit code for ${group.publisher}/${group.id}`)
-    if (result.report !== null && typeof result.report !== 'string') throw new Error(`refusing eval results artifact: invalid report for ${group.publisher}/${group.id}`)
     if (result.report !== null && Buffer.byteLength(result.report) > settings.max_report_bytes) throw new Error(`refusing eval results artifact: report exceeds configured cap for ${group.publisher}/${group.id}`)
     results.set(key, { status: result.status, exit_code: result.exit_code, report: result.report })
   }
@@ -289,95 +276,8 @@ const boundEvalResults = ({ file, config, commandOverride, plan, groups, baseHea
   }
 }
 
-const feedContext = feedsDir => {
-  const records = new Map()
-  let files = []
-  try {
-    files = fs.readdirSync(feedsDir).filter(file => file.endsWith('.json')).sort()
-  } catch {
-    return records
-  }
-  for (const file of files) {
-    let feed
-    try {
-      feed = JSON.parse(fs.readFileSync(path.join(feedsDir, file), 'utf8'))
-    } catch {
-      continue
-    }
-    if (feed?.spec !== 'model-eol/0.1' || !Array.isArray(feed.models)) continue
-    for (const entry of feed.models) {
-      for (const key of [entry.id, ...(entry.aliases ?? [])]) {
-        if (typeof key === 'string') records.set(`${feed.publisher}\0${key}`, { feed, entry })
-      }
-    }
-  }
-  return records
-}
-
-export const contextFor = (records, publisher, id, via) => {
-  const record = records.get(`${publisher}\0${id}`)
-  if (!record) return { announced: null, notes: [], entry: null }
-  const distribution = via ? (record.entry.distributions ?? []).find(item => item.via === via) : null
-  return {
-    announced: distribution ? distribution.announced ?? null : record.entry.announced ?? null,
-    notes: [record.feed.note, record.entry.notes].filter(Boolean),
-    entry: record.entry,
-  }
-}
-
-const ignoredModelIds = (plan, config) => {
-  const ignored = new Set(config.ignore.models)
-  const ids = new Set()
-  for (const item of [...plan.items, ...plan.issues]) {
-    if (item.id && (ignored.has(item.id) || ignored.has(item.matched))) ids.add(item.id)
-  }
-  return ids
-}
-
-const isIgnored = (entry, root, config, ignoredIds) => {
-  if (entry.id && ignoredIds.has(entry.id)) return true
-  if (entry.id && config.ignore.models.includes(entry.id)) return true
-  if (entry.matched && config.ignore.models.includes(entry.matched)) return true
-  return matchesAnyGlob(repoPath(entry.file, root), config.ignore.paths)
-}
-
-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 ?? ''}`
-    if (!groups.has(key)) {
-      groups.set(key, {
-        kind: 'model',
-        id: item.id,
-        publisher: item.publisher,
-        items: [],
-        via,
-        branch: branchFor(item.publisher, item.id, via),
-        context: contextFor(records, item.publisher, item.id, via),
-      })
-    }
-    groups.get(key).items.push(item)
-  }
-  for (const group of groups.values()) {
-    group.items.sort((a, b) => `${a.file}:${a.line}:${a.occurrence}`.localeCompare(`${b.file}:${b.line}:${b.occurrence}`))
-    group.feedDigest = groupDigest(group.items, group.context?.entry)
-  }
-  return [...groups.values()].sort((a, b) => `${a.publisher}/${a.id}`.localeCompare(`${b.publisher}/${b.id}`))
-}
-
-// the capture section reads clocks outside the plan items, so they join the digest that gates body updates
-const clockRows = entry => entry
-  ? {
-      shutdown: entry.shutdown ?? null,
-      date_precision: entry.date_precision ?? null,
-      distributions: itemDigest((entry.distributions ?? []).map(row => ({ via: row.via, shutdown: row.shutdown ?? null, status: row.status ?? null, date_precision: row.date_precision ?? null }))),
-    }
-  : null
-const groupDigest = (items, entry) => sha256(stableJson({ items: itemDigest(items), clocks: clockRows(entry) }))
+const buildModelGroups = (plan, config, root, records) =>
+  modelGroups(plan, config, root, records, (publisher, id, via) => ({ branch: branchFor(publisher, id, via) }))
 
 const buildIssueGroups = (plan, config, root, records) => {
   const ignoredIds = ignoredModelIds(plan, config)

package/bot/lib/common.mjs

@@ -1,27 +1,7 @@
-import crypto from 'node:crypto'
-import path from 'node:path'
+import { sha256 } from '../../lib/digests.mjs'
 
 export { matchesAnyGlob, matchesGlob } from '../../lib/glob.mjs'
-
-export const sha256 = value => crypto.createHash('sha256').update(value).digest('hex')
-
-const stableValue = value => {
-  if (Array.isArray(value)) return value.map(stableValue)
-  if (value && typeof value === 'object') {
-    return Object.fromEntries(Object.keys(value).sort().map(key => [key, stableValue(value[key])]))
-  }
-  return value
-}
-
-export const stableJson = value => JSON.stringify(stableValue(value))
-
-export const sortedJsonDigest = values => {
-  const sorted = values.slice().sort((a, b) => {
-    const [left, right] = [stableJson(a), stableJson(b)]
-    return left < right ? -1 : left > right ? 1 : 0
-  })
-  return sha256(stableJson(sorted))
-}
+export { activeWaiver, itemDigest, repoPath, sha256, sortedJsonDigest, stableJson } from '../../lib/digests.mjs'
 
 const safeSegment = value => {
   const result = String(value ?? '')
@@ -45,12 +25,6 @@ export const daysRemaining = (shutdown, now = new Date()) => {
   return Math.ceil((new Date(`${shutdown}T00:00:00Z`) - now) / 86400000)
 }
 
-export const repoPath = (file, root) => {
-  const absolute = path.isAbsolute(file) ? file : path.resolve(root, file)
-  const relative = path.relative(root, absolute)
-  return relative.split(path.sep).join('/').replace(/^\.\//, '')
-}
-
 export const metadataLine = metadata => `<!-- model-eol ${JSON.stringify(metadata).replaceAll('-->', '\\u002d\\u002d\\u003e')} -->`
 
 export const hasMetadataMarker = body => String(body ?? '').includes('<!-- model-eol')
@@ -82,10 +56,6 @@ 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.`

package/check.mjs

@@ -10,11 +10,13 @@
 //   node check.mjs alert [paths...] [--format github|markdown|badge] [--json]
 //   node check.mjs plan [paths...] [--days N] [--scope all|direct] [--via DISTRIBUTOR] [--feeds DIR]
 //   node check.mjs apply --plan plan.json [--dry-run]
-//   node check.mjs validate document.json [...] [--type feed|config|check|inventory|schedule|alert|plan]
+//   node check.mjs validate document.json [...] [--type feed|config|check|inventory|schedule|alert|plan|eval|feed-refresh-receipt|npm-release-result|verification]
+//   node check.mjs verify RECEIPT [inputs] [--require-all] [--json]
 //
 // exit codes: check/alert 0 = clear, 1 = finding, 2 = usage error;
 // apply 0 = all items applied, 1 = item refused, 2 = usage or plan error;
-// validate 0 = every document valid, 2 = usage, parse, schema, or semantic error.
+// validate 0 = every document valid, 2 = usage, parse, schema, or semantic error;
+// verify 0 = verified or partial, 1 = mismatch (or partial with --require-all), 2 = usage, read, structural, or schema error.
 
 import fs from 'node:fs'
 import path from 'node:path'
@@ -48,6 +50,7 @@ import {
 } from './lib/reports.mjs'
 import { addedLinesForTargets, filterFindingsToChanged, gitRootFor, incompleteScanNotes, scanTargets } from './lib/scanner.mjs'
 import { DOCUMENT_TYPES, formatDocumentErrors, validateDocumentFile } from './lib/validate-document.mjs'
+import { SUPPORTED_RECEIPT_SCHEMAS, VERIFY_INPUTS, VerifyError, formatVerification, printable, verifyReceipt } from './lib/verify.mjs'
 
 const rootForTarget = target => {
   const absolute = path.resolve(target)
@@ -96,7 +99,7 @@ const repoPathForFile = (file, roots) => {
 }
 
 const main = () => {
-const COMMANDS = new Set(['check', 'inventory', 'schedule', 'alert', 'plan', 'apply', 'validate', 'help'])
+const COMMANDS = new Set(['check', 'inventory', 'schedule', 'alert', 'plan', 'apply', 'validate', 'verify', 'help'])
 const args = process.argv.slice(2)
 
 if (args[0] === '--help' || args[0] === '-h') args[0] = 'help'
@@ -119,13 +122,20 @@ try {
       'dry-run': { type: 'boolean' },
       changed: { type: 'string' },
       type: { type: 'string' },
+      'feeds-dir': { type: 'string' },
+      commit: { type: 'string' },
+      'run-url': { type: 'string' },
+      package: { type: 'string' },
+      'source-commit': { type: 'string' },
+      version: { type: 'string' },
+      'require-all': { type: 'boolean' },
       help: { type: 'boolean', short: 'h' },
     },
     allowPositionals: true,
     help: 'node check.mjs --help',
   })
 } catch (error) {
-  console.error(error.message)
+  console.error(printable(error.message))
   return 2
 }
 
@@ -152,7 +162,9 @@ Usage:
   node check.mjs alert [paths...] [--config FILE] [--days N] [--scope all|direct] [--format github|markdown|badge] [--json]
   node check.mjs plan [paths...] [--config FILE] [--days N] [--scope all|direct] [--via DISTRIBUTOR] [--feeds DIR] [--allow-incomplete]
   node check.mjs apply --plan plan.json [--dry-run]
-  node check.mjs validate document.json [...] [--type feed|config|check|inventory|schedule|alert|plan]
+  node check.mjs validate document.json [...] [--type feed|config|check|inventory|schedule|alert|plan|eval|feed-refresh-receipt|npm-release-result|verification]
+  node check.mjs verify RECEIPT [--feeds-dir DIR] [--commit SHA] [--run-url URL] [--package FILE.tgz]
+                        [--source-commit SHA] [--version X.Y.Z] [--plan FILE] [--config FILE] [--require-all] [--json]
 
 Commands:
   check       Fail when tracked model IDs are retired or retiring within --days.
@@ -164,8 +176,38 @@ Commands:
   alert       Emit GitHub Actions annotations, Markdown, or a Shields badge JSON and fail on errors.
   plan        Emit a JSON migration plan with only safely patchable direct API references.
   apply       Apply a plan with line-hash and occurrence checks; use --dry-run to preview.
-  validate    Validate a feed, config, check, inventory, schedule, alert, or plan document.
+  validate    Validate a feed, config, check, inventory, schedule, alert, or plan document,
+              an eval, feed-refresh-receipt, or npm-release-result receipt, or a verify --json report.
               The type is inferred from its discriminator or .model-eol.json filename unless --type is set.
+  verify      Check what a receipt claims against inputs you supply, offline. The receipt kind
+              comes from its schema value:
+                ${SUPPORTED_RECEIPT_SCHEMAS.join('\n                ')}
+              Each claim is verified, mismatch, not-checked (its input was not supplied), or
+              not-applicable (a no-release receipt; a release input given for one adds a mismatched
+              released claim). Nothing is read from the current directory or git.
+              The result is verified only when every applicable claim is; partial means nothing
+              mismatched but some claim was not checked; mismatch means at least one claim failed.
+              --json emits a model-eol/verification@0.1 document.
+              Eval outcomes (status, exit_code, report) are never claims: verified means the
+              manifest is bound to the supplied commit, plan, config, and feeds, not that evals passed.
+
+Verify inputs:
+  --feeds-dir DIR       Feeds directory itself (DIR/*.json, e.g. ./feeds), not a repository root.
+                        Feed-refresh: every feeds/*.json digest; missing, extra, and changed files mismatch.
+                        Eval: with --plan and --config, recomputes each result's feed_digest
+                        (--plan and --config alone already fix the expected result set).
+  --commit SHA          Feed-refresh refresh_commit, npm-release release_commit, or eval base_sha.
+  --run-url URL         Feed-refresh refresh_run, compared after HTTPS URL normalization.
+  --package FILE.tgz    npm-release registry_integrity: sha512 SRI of the tarball bytes. No registry lookup.
+  --source-commit SHA   npm-release source_commit.
+  --version X.Y.Z       npm-release version (the tag is bound to it as vX.Y.Z).
+  --plan FILE           Eval plan_digest from a model-eol.plan/0.1 document; also needed for feed digests.
+  --config FILE         Eval eval_config_digest and configured, from .model-eol.json (use a file holding {}
+                        for a repository without one). MODEL_EOL_EVAL_COMMAND overrides eval.command as it
+                        does for the bot, and the output says when it applied.
+  --require-all         Exit 1 when the result is partial. A release gate passes --package, --version,
+                        --commit, and --require-all: a no-release receipt then mismatches.
+  SHA inputs are 40-64 hexadecimal characters; uppercase is lowercased.
 
 Scopes:
   all        Check every tracked model ID found. This preserves the original behavior.
@@ -176,9 +218,10 @@ Configuration:
   --config FILE selects an explicit config. Explicit CLI flags override config values.
 
 Exit codes:
-  0  Clean, or report generated successfully.
-  1  Findings, alert errors, or refused apply items.
-  2  Usage, feed, scan, plan, or validation errors.
+  0  Clean, or report generated successfully. verify: verified or partial (no claim mismatched).
+  1  Findings, alert errors, or refused apply items. verify: a claim mismatched, or partial with --require-all.
+  2  Usage, feed, scan, plan, or validation errors. verify: usage error, unreadable file, structurally
+     invalid receipt, or unsupported receipt schema.
   3  Output stream failure other than EPIPE.
 `)
   return 0
@@ -193,6 +236,37 @@ if (values.via === '') {
   return 2
 }
 
+if (command === 'verify') {
+  const allowedOptions = new Set([...VERIFY_INPUTS, 'require-all', 'json'])
+  const unsupported = Object.keys(values).find(option => !allowedOptions.has(option))
+  if (positionals.length !== 1 || unsupported) {
+    const detail = unsupported ? `; --${unsupported} is not supported by verify` : ''
+    console.error(`verify requires exactly one RECEIPT${detail}; run node check.mjs --help for usage`)
+    return 2
+  }
+  let report
+  try {
+    report = verifyReceipt({
+      file: positionals[0],
+      inputs: Object.fromEntries(VERIFY_INPUTS.map(flag => [flag, values[flag]])),
+      env: process.env,
+    })
+  } catch (error) {
+    console.error(printable(error instanceof VerifyError
+      ? `model-eol verify: ${error.message}`
+      : `model-eol verify: unexpected error, nothing was checked: ${error?.message ?? error}`))
+    return 2
+  }
+  console.log(AS_JSON ? JSON.stringify(report, null, 2) : formatVerification(report))
+  if (report.result === 'mismatch') return 1
+  return report.result === 'partial' && values['require-all'] ? 1 : 0
+}
+const verifyOnly = ['feeds-dir', 'commit', 'run-url', 'package', 'source-commit', 'version', 'require-all'].find(option => values[option] !== undefined)
+if (verifyOnly) {
+  console.error(`--${verifyOnly} is only supported by the verify command`)
+  return 2
+}
+
 if (command === 'apply') {
   if (!PLAN_FILE || positionals.length) {
     console.error('apply requires --plan plan.json and accepts no target paths')