model-eol 0.8.4 → 0.9.0

package/lib/verify.mjs

@@ -0,0 +1,359 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { TextDecoder } from 'node:util'
+
+import { loadConfig } from './config.mjs'
+import { effectiveEval, evalConfigDigest, evalIdentity, feedContext, modelGroups, planDigest, sha256 } from './digests.mjs'
+import {
+  EVAL_RESULTS_SCHEMA,
+  FEED_REFRESH_RECEIPT_SCHEMA,
+  RELEASE_RECEIPT_SCHEMA,
+  FEED_NAME_PATTERN,
+  SHA_PATTERN,
+  VERIFICATION_SCHEMA,
+  assertHttpsUrl,
+  hashFeedFiles,
+  sha512Integrity,
+  verificationResult,
+} from './receipts.mjs'
+import { assertValidPlanDocument, formatDocumentErrors, validateDocument } from './validate-document.mjs'
+
+export class VerifyError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'VerifyError'
+    this.exitCode = 2
+  }
+}
+
+const NAMED_CONTROLS = new Map([['\n', '\\n'], ['\r', '\\r'], ['\t', '\\t']])
+
+export const printable = value => String(value).replace(/[\u0000-\u001f\u007f-\u009f]/g, character => {
+  const code = character.charCodeAt(0)
+  return NAMED_CONTROLS.get(character) ?? (code < 0x80 ? `\\x${code.toString(16).padStart(2, '0')}` : `\\u${code.toString(16).padStart(4, '0')}`)
+})
+
+const refuse = message => {
+  throw new VerifyError(message)
+}
+
+const KINDS = new Map([
+  [FEED_REFRESH_RECEIPT_SCHEMA, { type: 'feed-refresh-receipt', inputs: ['feeds-dir', 'commit', 'run-url'] }],
+  [RELEASE_RECEIPT_SCHEMA, { type: 'npm-release-result', inputs: ['package', 'commit', 'source-commit', 'version'] }],
+  [EVAL_RESULTS_SCHEMA, { type: 'eval', inputs: ['commit', 'plan', 'config', 'feeds-dir'] }],
+])
+
+export const SUPPORTED_RECEIPT_SCHEMAS = Object.freeze([...KINDS.keys()])
+export const VERIFY_INPUTS = Object.freeze(['feeds-dir', 'commit', 'run-url', 'package', 'source-commit', 'version', 'plan', 'config'])
+
+const VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/
+const utf8Decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true })
+
+const readReceipt = file => {
+  let bytes
+  try {
+    bytes = fs.readFileSync(file)
+  } catch (error) {
+    refuse(`could not read receipt ${file}: ${error.message}`)
+  }
+  let document
+  try {
+    document = JSON.parse(utf8Decoder.decode(bytes))
+  } catch (error) {
+    refuse(`receipt ${file} is not UTF-8 JSON: ${error.message}`)
+  }
+  return { bytes, document }
+}
+
+const commitInput = (value, flag) => {
+  const commit = String(value).toLowerCase()
+  if (!SHA_PATTERN.test(commit)) refuse(`${flag} must be a 40-64 character hexadecimal Git commit`)
+  return commit
+}
+
+const runUrlInput = value => {
+  try {
+    return assertHttpsUrl(value, '--run-url')
+  } catch (error) {
+    refuse(error.message)
+  }
+}
+
+const versionInput = value => {
+  if (!VERSION_PATTERN.test(value)) refuse('--version must be an exact X.Y.Z version without a leading v')
+  return value
+}
+
+const readBytes = (file, flag) => {
+  try {
+    return fs.readFileSync(file)
+  } catch (error) {
+    refuse(`could not read ${flag} ${file}: ${error.message}`)
+  }
+}
+
+const feedsDirInput = dir => {
+  let stat
+  try {
+    stat = fs.statSync(dir)
+  } catch (error) {
+    refuse(`could not read --feeds-dir ${dir}: ${error.message}`)
+  }
+  if (!stat.isDirectory()) refuse(`--feeds-dir ${dir} is not a directory`)
+  let nested = false
+  try {
+    nested = fs.statSync(path.join(dir, 'feeds')).isDirectory()
+  } catch {
+  }
+  if (nested) refuse(`--feeds-dir takes the feeds directory itself, not a repository root; pass ${path.join(dir, 'feeds')}`)
+  try {
+    const stray = fs.readdirSync(dir).find(name => name.endsWith('.json') && !FEED_NAME_PATTERN.test(name))
+    if (stray !== undefined) refuse(`--feeds-dir ${dir} holds ${JSON.stringify(stray)}, which is not a feeds/*.json name a receipt writer can emit`)
+    return hashFeedFiles(dir)
+  } catch (error) {
+    if (error instanceof VerifyError) throw error
+    refuse(`could not read --feeds-dir ${dir}: ${error.message}`)
+  }
+}
+
+const planInput = file => {
+  let plan
+  try {
+    plan = JSON.parse(utf8Decoder.decode(readBytes(file, '--plan')))
+  } catch (error) {
+    if (error instanceof VerifyError) throw error
+    refuse(`--plan ${file} is not UTF-8 JSON: ${error.message}`)
+  }
+  if (plan?.plan_schema !== 'model-eol.plan/0.1') refuse(`--plan ${file} has plan schema ${plan?.plan_schema ?? 'missing'}; expected model-eol.plan/0.1`)
+  try {
+    return assertValidPlanDocument(plan)
+  } catch (error) {
+    refuse(`--plan ${file} is not a valid plan: ${error.message}`)
+  }
+}
+
+const configInput = (file, env) => {
+  let config
+  try {
+    config = loadConfig(file, { allowMissing: false })
+  } catch (error) {
+    refuse(`--config ${file}: ${error.message}`)
+  }
+  const override = env.MODEL_EOL_EVAL_COMMAND || null
+  const settings = effectiveEval(config, override)
+  const note = override === null
+    ? ''
+    : settings.command === override
+      ? ' with the MODEL_EOL_EVAL_COMMAND override from the environment'
+      : ' (MODEL_EOL_EVAL_COMMAND is set but blank, so eval.command applies)'
+  return { config, settings, label: `--config ${file}${note}` }
+}
+
+const compare = (claim, expected, actual, input) => ({
+  claim,
+  status: expected === actual ? 'verified' : 'mismatch',
+  expected,
+  actual,
+  input,
+})
+
+const notChecked = (claim, input) => ({ claim, status: 'not-checked', input })
+
+const notApplicable = (claim, input) => input === undefined
+  ? { claim, status: 'not-applicable' }
+  : { claim, status: 'not-applicable', input }
+
+const flagLabel = (flag, value) => `--${flag} ${value}`
+
+const feedClaims = (receiptFeeds, dir) => {
+  if (dir === undefined) return receiptFeeds.map(feed => notChecked(feed.path, '--feeds-dir DIR'))
+  const actual = new Map(feedsDirInput(dir).map(feed => [feed.path, feed.sha256]))
+  const expected = new Map(receiptFeeds.map(feed => [feed.path, feed.sha256]))
+  return [...new Set([...expected.keys(), ...actual.keys()])]
+    .sort((left, right) => left.localeCompare(right))
+    .map(file => compare(file, expected.get(file) ?? null, actual.get(file) ?? null, flagLabel('feeds-dir', dir)))
+}
+
+const refreshClaims = (receipt, inputs) => [
+  ...feedClaims(receipt.feeds, inputs['feeds-dir']),
+  inputs.commit === undefined
+    ? notChecked('refresh_commit', '--commit SHA')
+    : compare('refresh_commit', receipt.refresh_commit, commitInput(inputs.commit, '--commit'), flagLabel('commit', inputs.commit)),
+  inputs['run-url'] === undefined
+    ? notChecked('refresh_run', '--run-url URL')
+    : compare('refresh_run', assertHttpsUrl(receipt.refresh_run, 'refresh_run'), runUrlInput(inputs['run-url']), flagLabel('run-url', inputs['run-url'])),
+]
+
+const releaseClaims = (receipt, inputs) => {
+  const sourceCommit = inputs['source-commit'] === undefined
+    ? notChecked('source_commit', '--source-commit SHA')
+    : compare('source_commit', receipt.source_commit, commitInput(inputs['source-commit'], '--source-commit'), flagLabel('source-commit', inputs['source-commit']))
+  const given = flag => inputs[flag] === undefined ? undefined : flagLabel(flag, inputs[flag])
+  if (!receipt.released) {
+    const releaseInputs = ['commit', 'version', 'package'].map(given).filter(Boolean)
+    return [
+      sourceCommit,
+      ...(releaseInputs.length ? [{ claim: 'released', status: 'mismatch', expected: false, actual: true, input: releaseInputs.join(', ') }] : []),
+      notApplicable('release_commit', given('commit')),
+      notApplicable('version', given('version')),
+      notApplicable('registry_integrity', given('package')),
+    ]
+  }
+  return [
+    sourceCommit,
+    inputs.commit === undefined
+      ? notChecked('release_commit', '--commit SHA')
+      : compare('release_commit', receipt.release_commit, commitInput(inputs.commit, '--commit'), given('commit')),
+    inputs.version === undefined
+      ? notChecked('version', '--version X.Y.Z')
+      : compare('version', receipt.version, versionInput(inputs.version), given('version')),
+    inputs.package === undefined
+      ? notChecked('registry_integrity', '--package FILE.tgz')
+      : compare('registry_integrity', receipt.registry_integrity, sha512Integrity(readBytes(inputs.package, '--package')), given('package')),
+  ]
+}
+
+// JSON-quoted parts keep labels injective; '' and null via share one identity, as in evalIdentity
+const resultLabel = ({ publisher, id, via }) => `results[${[publisher, id, via || null].map(part => JSON.stringify(part)).join(', ')}]`
+
+const plannedGroups = (plan, config, feedsDir) => {
+  // plan files are root-relative as `model-eol plan .` writes them, so any absolute root reproduces the bot's ignore matching
+  try {
+    return modelGroups(plan, config.config, path.resolve('/'), feedsDir === undefined ? new Map() : feedContext(feedsDir))
+  } catch (error) {
+    refuse(`--feeds-dir ${feedsDir} holds a malformed feed for a planned model: ${error.message}`)
+  }
+}
+
+const evalResultClaims = (receipt, { plan, config, inputs }) => {
+  const feedsDir = inputs['feeds-dir']
+  if (feedsDir !== undefined) feedsDirInput(feedsDir)
+  if (!receipt.configured) return []
+  const claims = []
+  const planned = plan && config
+    ? new Map(plannedGroups(plan, config, feedsDir).map(group => [evalIdentity(group.publisher, group.id, group.via), group]))
+    : null
+  const setInput = planned ? `${flagLabel('plan', inputs.plan)} and ${config.label}` : null
+  const digestInput = planned && feedsDir !== undefined ? `${setInput} and ${flagLabel('feeds-dir', feedsDir)}` : null
+  if (!planned) claims.push(notChecked('results', '--plan FILE and --config FILE'))
+  const copies = new Map()
+  for (const result of receipt.results) {
+    const key = evalIdentity(result.publisher, result.id, result.via)
+    const label = resultLabel(result)
+    const copy = (copies.get(key) ?? 0) + 1
+    copies.set(key, copy)
+    if (copy > 1) {
+      claims.push({ claim: `${label} (duplicate ${copy})`, status: 'mismatch', expected: true, actual: false, input: 'the receipt itself (one result per identity)' })
+      continue
+    }
+    if (!planned) {
+      claims.push(notChecked(`${label}.feed_digest`, '--plan FILE, --config FILE, and --feeds-dir DIR'))
+      continue
+    }
+    const group = planned.get(key)
+    if (!group) {
+      claims.push({ claim: label, status: 'mismatch', expected: true, actual: false, input: setInput })
+      continue
+    }
+    claims.push({ claim: label, status: 'verified', expected: true, actual: true, input: setInput })
+    claims.push(digestInput
+      ? compare(`${label}.feed_digest`, result.feed_digest, group.feedDigest, digestInput)
+      : notChecked(`${label}.feed_digest`, '--feeds-dir DIR'))
+  }
+  for (const [key, group] of planned ?? []) {
+    if (!copies.has(key)) claims.push({ claim: resultLabel(group), status: 'mismatch', expected: false, actual: true, input: setInput })
+  }
+  return claims
+}
+
+const evalClaims = (receipt, inputs, env) => {
+  const plan = inputs.plan === undefined ? null : planInput(inputs.plan)
+  const config = inputs.config === undefined ? null : configInput(inputs.config, env)
+  return [
+    inputs.commit === undefined
+      ? notChecked('base_sha', '--commit SHA')
+      : compare('base_sha', receipt.base_sha, commitInput(inputs.commit, '--commit'), flagLabel('commit', inputs.commit)),
+    plan
+      ? compare('plan_digest', receipt.plan_digest, planDigest(plan), flagLabel('plan', inputs.plan))
+      : notChecked('plan_digest', '--plan FILE'),
+    config
+      ? compare('eval_config_digest', receipt.eval_config_digest, evalConfigDigest(config.settings), config.label)
+      : notChecked('eval_config_digest', '--config FILE'),
+    config
+      ? compare('configured', receipt.configured, Boolean(config.settings.command), config.label)
+      : notChecked('configured', '--config FILE'),
+    ...evalResultClaims(receipt, { plan, config, inputs }),
+  ]
+}
+
+export const verifyReceipt = ({ file, inputs = {}, env = process.env }) => {
+  const { bytes, document } = readReceipt(file)
+  const schema = typeof document?.schema === 'string' ? document.schema : null
+  const kind = KINDS.get(schema)
+  if (!kind) {
+    refuse(`unsupported receipt schema ${schema === null ? '(missing)' : JSON.stringify(schema)}; supported schemas: ${SUPPORTED_RECEIPT_SCHEMAS.join(', ')}`)
+  }
+  const foreign = Object.keys(inputs).filter(flag => inputs[flag] !== undefined && !kind.inputs.includes(flag))
+  if (foreign.length) refuse(`${foreign.map(flag => `--${flag}`).join(', ')} does not apply to ${schema} receipts; accepted inputs: ${kind.inputs.map(flag => `--${flag}`).join(', ')}`)
+  const structural = validateDocument(document, { type: kind.type })
+  if (structural.errors.length) refuse(`structurally invalid ${schema} receipt ${file}: ${formatDocumentErrors(structural.errors).join('; ')}`)
+  const claims = kind.type === 'feed-refresh-receipt'
+    ? refreshClaims(document, inputs)
+    : kind.type === 'npm-release-result'
+      ? releaseClaims(document, inputs)
+      : evalClaims(document, inputs, env)
+  return {
+    schema: VERIFICATION_SCHEMA,
+    receipt: {
+      path: file,
+      schema,
+      sha256: sha256(bytes),
+      ...(kind.type === 'feed-refresh-receipt'
+        ? { state: document.state, checked_at: document.checked_at, ...(document.state === 'pending' ? { pending_pr: document.pending_pr } : {}) }
+        : {}),
+      ...(kind.type === 'npm-release-result' ? { released: document.released } : {}),
+    },
+    structural: 'valid',
+    claims,
+    result: verificationResult(claims),
+  }
+}
+
+const shown = value => value === null ? '(absent)' : printable(value)
+
+export const formatVerification = report => {
+  const info = report.receipt
+  const names = report.claims.map(claim => printable(claim.claim))
+  const width = Math.max(0, ...names.map(name => name.length))
+  const lines = [
+    `receipt ${printable(info.path)}`,
+    `  schema ${printable(info.schema)}`,
+    `  sha256 ${printable(info.sha256)}`,
+    ...(info.state !== undefined
+      ? [`  state ${printable(info.state)}, checked ${printable(info.checked_at)}${info.pending_pr !== undefined ? `, pending feed PR ${printable(info.pending_pr)}` : ''} (information only; not a claim)`]
+      : []),
+    ...(info.released !== undefined
+      ? [`  released ${info.released}${info.released ? '' : ' (the receipt records no release; a release gate must also pass --package, --version, and --commit)'} (information only; not a claim)`]
+      : []),
+    'structural: valid',
+  ]
+  for (const [index, claim] of report.claims.entries()) {
+    const input = claim.input === undefined ? undefined : printable(claim.input)
+    const detail = claim.status === 'verified'
+      ? `${shown(claim.actual)} (${input})`
+      : claim.status === 'mismatch'
+        ? `receipt ${shown(claim.expected)}, ${input} gives ${shown(claim.actual)}`
+        : claim.status === 'not-checked'
+          ? `needs ${input}`
+          : `the receipt records no release${input ? `; ${input} has nothing to check` : ''}`
+    lines.push(`  ${claim.status.padEnd(14)} ${names[index].padEnd(width)}  ${detail}`)
+  }
+  const unchecked = report.claims.filter(claim => claim.status === 'not-checked').length
+  const mismatched = report.claims.filter(claim => claim.status === 'mismatch').length
+  lines.push(report.result === 'mismatch'
+    ? `result: mismatch (${mismatched} claim${mismatched === 1 ? '' : 's'} contradicted by the supplied inputs)`
+    : report.result === 'partial'
+      ? `result: partial (no mismatch, but ${unchecked} claim${unchecked === 1 ? ' was' : 's were'} not checked; supply the inputs above, or use --require-all to fail)`
+      : 'result: verified (every applicable claim matched the supplied inputs)')
+  return lines.join('\n')
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "model-eol",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "description": "AI model deprecation feeds with a zero-dependency checker, inventory CLI, and migration bot.",
   "type": "module",
   "bin": {
@@ -8,7 +8,7 @@
     "model-eol-bot": "bot/bot.mjs"
   },
   "scripts": {
-    "test": "node test/run.mjs && node refresh/test/run.mjs && node bot/test/run.mjs && node scripts/test-action-contract.mjs && node scripts/test-document-validation.mjs && node scripts/test-eval-harness.mjs && node bot/test/package.mjs && node scripts/test-feed-changelog.mjs && node scripts/test-public-site.mjs"
+    "test": "node test/run.mjs && node refresh/test/run.mjs && node bot/test/run.mjs && node scripts/test-action-contract.mjs && node scripts/test-document-validation.mjs && node scripts/test-receipts.mjs && node scripts/test-verify.mjs && node scripts/test-eval-harness.mjs && node bot/test/package.mjs && node scripts/test-feed-changelog.mjs && node scripts/test-public-site.mjs"
   },
   "repository": {
     "type": "git",

package/schema/model-eol.eval.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://thossullivan.github.io/model-eol/schema/0.1/model-eol.eval.schema.json",
+  "title": "model-eol eval results manifest",
+  "description": "Eval results manifest `model-eol.eval/0.1` written by `model-eol-bot evaluate`. It binds one pass, fail, or timeout result per planned migration group to the evaluated default-branch commit (base_sha), the SHA-256 of the plan without its generated time (plan_digest), the SHA-256 of the effective eval settings (eval_config_digest), and each group's feed digest. Publication refuses a manifest whose digests, base commit, configured state, or result identities do not match its own independently regenerated plan. Compatibility: additive changes keep this version; any change that makes an existing manifest invalid or changes what a digest covers is a new version, and validators reject unknown versions. Matching its digests, base commit, and result identities against a regenerated plan, and the per-report byte cap from eval.max_report_bytes, need the consumer's repository and stay in code. Calendar validity of generated relies on `format: date-time`, which many Draft-07 validators treat as an annotation unless format validation is enabled; model-eol's validator enforces it.",
+  "type": "object",
+  "required": ["schema", "generated", "base_sha", "plan_digest", "eval_config_digest", "configured", "results"],
+  "properties": {
+    "schema": { "const": "model-eol.eval/0.1" },
+    "generated": { "$ref": "#/definitions/utcInstant" },
+    "base_sha": { "$ref": "#/definitions/gitCommit" },
+    "plan_digest": { "$ref": "#/definitions/sha256" },
+    "eval_config_digest": { "$ref": "#/definitions/sha256" },
+    "configured": { "type": "boolean" },
+    "results": { "type": "array", "items": { "$ref": "#/definitions/result" } }
+  },
+  "additionalProperties": false,
+  "oneOf": [
+    { "required": ["configured"], "properties": { "configured": { "const": true } } },
+    { "required": ["configured"], "properties": { "configured": { "const": false }, "results": { "maxItems": 0 } } }
+  ],
+  "definitions": {
+    "utcInstant": {
+      "type": "string",
+      "format": "date-time",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]+)?Z$"
+    },
+    "gitCommit": { "type": "string", "pattern": "^[0-9a-f]{40,64}$" },
+    "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "result": {
+      "type": "object",
+      "required": ["publisher", "id", "via", "feed_digest", "status", "exit_code", "report"],
+      "properties": {
+        "publisher": { "type": "string", "minLength": 1 },
+        "id": { "type": "string", "minLength": 1 },
+        "via": { "type": ["string", "null"] },
+        "feed_digest": { "$ref": "#/definitions/sha256" },
+        "status": { "enum": ["pass", "fail", "timeout"] },
+        "exit_code": { "type": ["integer", "null"], "minimum": -9007199254740991, "maximum": 9007199254740991 },
+        "report": { "type": ["string", "null"] }
+      },
+      "additionalProperties": false,
+      "oneOf": [
+        { "required": ["status"], "properties": { "status": { "const": "pass" }, "exit_code": { "type": "integer", "minimum": 0, "maximum": 0 } } },
+        { "required": ["status"], "properties": { "status": { "enum": ["fail", "timeout"] } } }
+      ]
+    }
+  }
+}

package/schema/model-eol.feed-refresh-receipt.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://thossullivan.github.io/model-eol/schema/0.1/model-eol.feed-refresh-receipt.schema.json",
+  "title": "model-eol feed-refresh receipt",
+  "description": "Feed-refresh receipt `model-eol/feed-refresh-receipt@0.1` written by every successful feed-refresh run. It binds the refresh run URL (refresh_run), the commit the run checked (refresh_commit), and the check time (checked_at) to the SHA-256 of every feeds/*.json file the run produced. A clean receipt means the live sources matched those feeds; a pending receipt means the run opened or updated pending_pr with material changes. The public contract is published only when a receipt's digests match the exact feeds being published. Compatibility: additive changes keep this version; any change that makes an existing receipt invalid or changes what a digest covers is a new version, and validators reject unknown versions. Enforced in code, not by this schema: feeds must be sorted by path (String.prototype.localeCompare), and no two feeds may share a path. URLs: the writer always emits the WHATWG-normalized URL, and the code validator accepts any https URL that WHATWG URL parsing accepts without credentials. This schema's URL pattern is stricter than the code in some ways (it refuses an uppercase HTTPS scheme, empty userinfo such as https://@host, https:host without slashes, and surrounding whitespace) and looser than the normalized form in others (it allows an uppercase host or an explicit :443 port). Calendar validity of checked_at relies on `format: date-time`, which many Draft-07 validators treat as an annotation unless format validation is enabled; model-eol's validator enforces it.",
+  "type": "object",
+  "required": ["schema", "state", "changed", "pending", "checked_at", "refresh_run", "refresh_commit", "feeds"],
+  "properties": {
+    "schema": { "const": "model-eol/feed-refresh-receipt@0.1" },
+    "state": { "enum": ["clean", "pending"] },
+    "changed": { "type": "boolean" },
+    "pending": { "type": "boolean" },
+    "checked_at": {
+      "type": "string",
+      "format": "date-time",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]+)?Z$"
+    },
+    "refresh_run": { "$ref": "#/definitions/httpsUrl" },
+    "refresh_commit": { "type": "string", "pattern": "^[0-9a-f]{40,64}$" },
+    "feeds": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "$ref": "#/definitions/feed" }
+    },
+    "pending_pr": { "$ref": "#/definitions/httpsUrl" }
+  },
+  "additionalProperties": false,
+  "oneOf": [
+    {
+      "properties": {
+        "state": { "const": "clean" },
+        "changed": { "const": false },
+        "pending": { "const": false },
+        "pending_pr": false
+      }
+    },
+    {
+      "required": ["pending_pr"],
+      "properties": {
+        "state": { "const": "pending" },
+        "changed": { "const": true },
+        "pending": { "const": true }
+      }
+    }
+  ],
+  "definitions": {
+    "httpsUrl": {
+      "type": "string",
+      "format": "uri",
+      "pattern": "^https://[^\\s/?#@]+([/?#][^\\s]*)?$"
+    },
+    "feed": {
+      "type": "object",
+      "required": ["path", "sha256"],
+      "properties": {
+        "path": { "type": "string", "pattern": "^feeds/[a-z0-9][a-z0-9-]*\\.json$" },
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schema/model-eol.npm-release-result.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://thossullivan.github.io/model-eol/schema/0.1/model-eol.npm-release-result.schema.json",
+  "title": "model-eol npm release result",
+  "description": "npm release result `model-eol/npm-release-result@0.2` written by every npm-release run. It binds the workflow source commit (source_commit) to what the run published: either nothing (released false), or one exact stable 0.x version, its git tag, the release commit, and the npm registry tarball integrity (a canonical sha512 Subresource Integrity value). Downstream consumer checks install that exact version and compare the registry integrity instead of trusting npm's latest tag. Compatibility: additive changes keep this version; any change that makes an existing result invalid or changes what a digest covers is a new version, and validators reject unknown versions. Enforced in code, not by this schema: tag must equal \"v\" followed by version.",
+  "type": "object",
+  "required": ["schema", "released", "source_commit"],
+  "properties": {
+    "schema": { "const": "model-eol/npm-release-result@0.2" },
+    "released": { "type": "boolean" },
+    "source_commit": { "$ref": "#/definitions/gitCommit" },
+    "version": { "type": "string", "pattern": "^0\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$" },
+    "tag": { "type": "string", "pattern": "^v0\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$" },
+    "release_commit": { "$ref": "#/definitions/gitCommit" },
+    "registry_integrity": { "type": "string", "pattern": "^sha512-[A-Za-z0-9+/]{85}[AQgw]==$" }
+  },
+  "additionalProperties": false,
+  "oneOf": [
+    {
+      "properties": {
+        "released": { "const": false },
+        "version": false,
+        "tag": false,
+        "release_commit": false,
+        "registry_integrity": false
+      }
+    },
+    {
+      "required": ["version", "tag", "release_commit", "registry_integrity"],
+      "properties": {
+        "released": { "const": true }
+      }
+    }
+  ],
+  "definitions": {
+    "gitCommit": { "type": "string", "pattern": "^[0-9a-f]{40,64}$" }
+  }
+}

package/schema/model-eol.verification.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://thossullivan.github.io/model-eol/schema/0.1/model-eol.verification.schema.json",
+  "title": "model-eol receipt verification",
+  "description": "Verification report `model-eol/verification@0.1` emitted by `model-eol verify RECEIPT --json`. It names the receipt by path, schema, and the SHA-256 of its bytes, records that the receipt passed structural validation, and lists one entry per claim. A claim is verified (the supplied input reproduces the receipt's value), mismatch (it does not; expected is the receipt's value and actual is what the input produced, null when one side has no such entry), not-checked (input names the flag that would check it), or not-applicable (a no-release receipt makes no such claim). A no-release receipt checked with any release input (--commit, --version, --package) gets a released claim with status mismatch, expected false and actual true. For a feed-refresh receipt, receipt.state, receipt.checked_at, and receipt.pending_pr (exactly when state is pending, an https URL) are copied from the receipt as information; for an npm-release-result receipt, receipt.released is. They are not claims, and no other receipt kind carries them. A configured eval manifest checked with --plan and --config gets one claim per planned or recorded result identity, named results[publisher, id, via] with each part JSON-quoted; a duplicate identity is a mismatch on its own; without --plan and --config a not-checked results claim stands in for the set. Eval outcomes (status, exit_code, report, generated) are never claims: verified means the manifest is bound to the supplied inputs, not that the evals passed. Compatibility: additive changes keep this version; validators reject unknown versions. Enforced in code, not by this schema: claim names are unique; a verified claim with both expected and actual has them equal, a mismatch claim has them different, and a not-checked claim names its input; result is mismatch when any claim is mismatch, verified when every applicable claim is verified and at least one is, and partial otherwise.",
+  "type": "object",
+  "required": ["schema", "receipt", "structural", "claims", "result"],
+  "properties": {
+    "schema": { "const": "model-eol/verification@0.1" },
+    "receipt": {
+      "type": "object",
+      "required": ["path", "schema", "sha256"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "schema": { "enum": ["model-eol.eval/0.1", "model-eol/feed-refresh-receipt@0.1", "model-eol/npm-release-result@0.2"] },
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "state": { "enum": ["clean", "pending"] },
+        "checked_at": { "type": "string", "format": "date-time" },
+        "pending_pr": { "type": "string", "format": "uri", "pattern": "^https://[^/?#@]+([/?#]|$)" },
+        "released": { "type": "boolean" }
+      },
+      "additionalProperties": false,
+      "oneOf": [
+        {
+          "required": ["state", "checked_at"],
+          "properties": {
+            "schema": { "const": "model-eol/feed-refresh-receipt@0.1" },
+            "released": false
+          },
+          "oneOf": [
+            { "required": ["pending_pr"], "properties": { "state": { "const": "pending" } } },
+            { "properties": { "state": { "const": "clean" }, "pending_pr": false } }
+          ]
+        },
+        {
+          "required": ["released"],
+          "properties": {
+            "schema": { "const": "model-eol/npm-release-result@0.2" },
+            "state": false,
+            "checked_at": false,
+            "pending_pr": false
+          }
+        },
+        {
+          "properties": {
+            "schema": { "const": "model-eol.eval/0.1" },
+            "state": false,
+            "checked_at": false,
+            "pending_pr": false,
+            "released": false
+          }
+        }
+      ]
+    },
+    "structural": { "const": "valid" },
+    "claims": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/claim" }
+    },
+    "result": { "enum": ["verified", "partial", "mismatch"] }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "value": { "type": ["string", "boolean", "null"] },
+    "claim": {
+      "type": "object",
+      "required": ["claim", "status"],
+      "properties": {
+        "claim": { "type": "string", "minLength": 1 },
+        "status": { "enum": ["verified", "mismatch", "not-checked", "not-applicable"] },
+        "expected": { "$ref": "#/definitions/value" },
+        "actual": { "$ref": "#/definitions/value" },
+        "input": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    }
+  }
+}