@nebulacomponents/citable 1.9.0 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulacomponents/citable",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "Production-grade SEO, AEO, and GEO agent skill with auditable detection, claim governance, evidence validation, and multi-agent installation.",
   "keywords": [
     "seo",
@@ -90,14 +90,19 @@
     "ajv-formats": "^3.0.1",
     "csv-parse": "^7.0.1",
     "js-yaml": "^5.2.1",
-    "node-html-parser": "^9.0.0"
+    "node-html-parser": "^9.0.0",
+    "pdfjs-dist": "^6.1.200"
   },
   "peerDependencies": {
-    "playwright": ">=1.50.0"
+    "playwright": ">=1.50.0",
+    "tesseract.js": ">=7.0.0"
   },
   "peerDependenciesMeta": {
     "playwright": {
       "optional": true
+    },
+    "tesseract.js": {
+      "optional": true
     }
   }
 }

package/schemas/media-manifest.schema.json

@@ -0,0 +1,2 @@
+{
+  "$id":"citable://schemas/media-manifest.schema.json","$schema":"http://json-schema.org/draft-07/schema#","title":"Media evidence import manifest","type":"object","additionalProperties":false,"required":["version","items"],"properties":{"version":{"const":1},"items":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"required":["media_id","type","path","source_url","page_url","claim_ids","permission_status"],"properties":{"media_id":{"type":"string","pattern":"^MEDIA-[A-Z0-9][A-Z0-9_-]*$"},"type":{"type":"string","enum":["pdf","transcript","image"]},"path":{"type":"string","minLength":1},"source_url":{"type":["string","null"]},"page_url":{"type":["string","null"]},"claim_ids":{"type":"array","uniqueItems":true,"items":{"type":"string"}},"permission_status":{"type":"string","enum":["owner_authorized","licensed","public_unknown","internal"]},"image_src":{"type":"string"},"language":{"type":"string"},"published_at":{"type":"string","format":"date-time"}}}}}}

package/schemas/observation.schema.json

@@ -7,7 +7,7 @@
   "required": ["observation_id", "kind", "state", "collected_at", "collection_method", "confidence", "source", "evidence_hash", "data"],
   "properties": {
     "observation_id": { "type": "string", "minLength": 1 },
-    "kind": { "type": "string", "enum": ["render", "index", "citation", "citation_review", "crawler_log", "bing_webmaster", "passage", "canonical_freshness", "performance", "corroboration", "metric"] },
+    "kind": { "type": "string", "enum": ["render", "index", "citation", "citation_review", "crawler_log", "bing_webmaster", "passage", "canonical_freshness", "performance", "corroboration", "metric", "media_pdf", "media_transcript", "media_image"] },
     "state": { "type": "string", "enum": ["observed", "not_observed", "not_evidenced", "incomplete", "review_required", "failed"] },
     "collected_at": { "type": "string", "format": "date-time" },
     "collection_method": { "type": "string", "enum": ["live_api", "browser", "owner_import", "synthetic_fetch", "static_analysis", "human_review"] },

package/schemas/schedule.schema.json

@@ -0,0 +1,4 @@
+{
+  "$id":"citable://schemas/schedule.schema.json","$schema":"http://json-schema.org/draft-07/schema#","title":"Audit schedule registry","type":"object","additionalProperties":false,"required":["version","kind","updated","entries"],
+  "properties":{"version":{"const":1},"kind":{"const":"schedules"},"updated":{"type":"string","format":"date-time"},"entries":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["schedule_id","name","status","cron","owner","expected_tool_version","audit","retention_days","limitations"],"properties":{"schedule_id":{"type":"string","pattern":"^SCHEDULE-[A-Z0-9][A-Z0-9_-]*$"},"name":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","paused","retired"]},"cron":{"type":"string","minLength":5},"owner":{"type":"string","minLength":1},"expected_tool_version":{"type":"string","pattern":"^\\d+\\.\\d+\\.\\d+$"},"audit":{"type":"object","additionalProperties":false,"required":["target","scope"],"properties":{"target":{"type":"string","minLength":1},"scope":{"type":["string","null"]},"base_url":{"type":["string","null"]}}},"retention_days":{"type":"integer","minimum":1},"limitations":{"type":"array","minItems":1,"items":{"type":"string"}}}}}}
+}

package/skill/SKILL.md

@@ -7,7 +7,7 @@ description: >
   generative engine optimization, structured data governance, claim substantiation,
   crawler policy, entity consistency, content discoverability, or wants a site audited
   for how search and AI systems will retrieve, understand, cite, or recommend it.
-version: 1.9.0
+version: 1.11.0
 ---
 
 # Citable — evidence and change control for search and AI citation readiness
@@ -115,6 +115,9 @@ citable reviews prioritize [--write]
 citable reviews plan --input <json|yaml> [--write]
 citable reviews sample <sampling-plan-id> [--write]
 citable reviews evaluate
+citable schedules run <schedule-id> [--ref-date YYYY-MM-DD]
+citable project github <run-id>
+citable observe media --input <manifest.json> [--ocr]
 ```
 
 Audit scopes: `technical seo aeo geo architecture entity claims evidence schema
@@ -174,7 +177,8 @@ mandatory.
 `.citable/` holds YAML registries for queries, prompts, entities, claims,
   evidence, pages, crawlers, competitors, experiments, metrics, objectives,
   interventions, optional connection state, reviewers, review policies, and
-  governed exceptions, semantic review items, and sampling plans, all schema-validated
+  governed exceptions, semantic review items, sampling plans, and audit schedules,
+  all schema-validated
 (`schemas/*.schema.json`) with referential integrity checks. Rules:
 
 - Never overwrite registry content without history — use the loader/saver in

package/skill/commands/README.md

@@ -29,6 +29,8 @@ intent, not executability, so statuses are strict:
 | /citable evaluate | implemented — independent baseline/evaluation comparisons with inconclusive handling |
 | /citable governance validate / evaluate | implemented — validates reviewer and exception authority and emits immutable dispositions without changing failed findings |
 | /citable reviews queue / prioritize / plan / sample / evaluate | implemented — materiality queues, reproducible sampling, stale-decision checks, and independent disagreement adjudication |
+| /citable schedules run / project github | implemented — canonical scheduled audits and hash-bound non-authoritative GitHub projections |
+| /citable observe media | implemented — bounded PDF, transcript, image-context, optional OCR, and declared claim-link evidence |
 | /citable ingest, map-site, map-queries, map-prompts, map-entities, map-evidence | specified (ingest.md) |
 | /citable optimize-page | specified (optimize-page.md) — requires source-to-render mapping, claim-preserving rewrites, build execution, rollback; none of that is proven yet |
 | /citable create-page, answer-block, architect, interlink, consolidate, metadata | specified (page-work.md) |

package/skill/commands/delivery.md

@@ -0,0 +1,18 @@
+# Scheduling, projections, and differential delivery
+
+`citable schedules run <schedule-id>` executes the same canonical audit function
+used by direct CLI calls. Schedules are version-pinned and fail closed when
+paused, missing, invalid, or bound to another Citable version. The external
+cron service remains responsible for triggering the command; a declared cron
+does not prove execution. Schedule metadata is stored outside the finalized
+audit package and binds back to its manifest checksum.
+
+`citable project github <run-id>` creates GitHub annotation JSON as a
+non-authoritative projection. It records hashes of the source manifest and
+findings and never edits the run. Dashboards and check annotations must link to
+these artifacts rather than maintain separate finding state.
+
+`compare-snapshots` reports observed comparability dimensions: resource input,
+evidence artifact, detector set, configuration, observation method, tool
+version, and possible external-system change. These dimensions identify why
+runs may not be directly comparable; they do not establish causal attribution.

package/skill/commands/media-evidence.md

@@ -0,0 +1,17 @@
+# Media evidence collection
+
+Use `citable observe media --input <manifest.json>` for bounded local-media
+evidence. The manifest declares source URL, owning page, permission status, and
+linked claim IDs for each PDF, transcript, or image-context source.
+
+PDF collection extracts native text, basic metadata, and stable page anchors.
+It does not establish reading order, table structure, footnote linkage,
+signatures, revisions, scan accuracy, accessibility, or claim support.
+Transcript collection preserves cues but does not verify speakers, timing,
+accuracy, or source-media parity. Image collection records alt text, captions,
+and nearby figure text without inferring visual entailment.
+
+OCR is off by default. `--ocr` explicitly requests the optional `tesseract.js`
+path; an unavailable engine or image produces incomplete evidence, never guessed
+text. Every media-to-claim relationship is declarative and still requires
+human-authoritative semantic review.

package/src/cli/index.js

@@ -19,6 +19,7 @@ import { evaluateObjective, importMetrics, initializeObjective, validateObjectiv
 import { configureConnection, connectionStatus, discoverConnections, disconnectConnection, syncConnection, validateConnection } from '../commands/connect.js';
 import { evaluateDispositions, validateGovernance } from '../commands/governance.js';
 import { evaluateReviews, initializeSamplingPlan, prioritizeReviews, queueReviews, selectSample } from '../commands/reviews.js';
+import { projectGithub, runSchedule } from '../commands/delivery.js';
 
 const HELP = `citable — SEO / AEO / GEO audit, remediation, validation, and governance
 
@@ -42,7 +43,7 @@ Commands
   compare-snapshots [a b]   Regression diff between two audit runs
   action-plan [run]         Turn audit findings into ordered remediation work
   observe <mode>            Collect render, index, citation, log, Bing, passage,
-                            consensus, performance, or corroboration evidence
+                            consensus, performance, corroboration, or media evidence
   apply                     Apply a reviewed, hash-locked remediation spec
   monitor [runA runB]       Compare observation runs and emit regression alerts
   metrics import            Import declared metric observations from CSV/JSON
@@ -62,6 +63,8 @@ Commands
   reviews plan              Validate/add a sampling plan from --input
   reviews sample [plan]     Select a reproducible census or seeded random sample
   reviews evaluate          Detect stale decisions and require disagreement adjudication
+  schedules run [id]        Execute an active version-pinned audit schedule
+  project github [run]      Render non-authoritative GitHub annotations from a run
   self-upgrade              Check for a newer version and upgrade the npx cache
 
 Options
@@ -81,6 +84,7 @@ Options
   --access-token <token>    OAuth token (prefer provider environment variables)
   --endpoint <url>          Controlled citation adapter endpoint
   --repeat <count>          Repetitions per prompt for citation experiments
+  --ocr                     Explicitly request optional OCR for media images
   --write                   Persist registry changes (map-claims, substantiate)
   --json                    Machine-readable output only
 
@@ -93,6 +97,7 @@ function parseArgs(argv) {
     const a = argv[i];
     if (a === '--write') args.write = true;
     else if (a === '--json') args.json = true;
+    else if (a === '--ocr') args.ocr = true;
     else if (a === '--target') args.target = argv[++i];
     else if (a === '--base-url') args.baseUrl = argv[++i];
     else if (a === '--ref-date') args.refDate = argv[++i];
@@ -272,6 +277,18 @@ export async function main(argv = process.argv.slice(2), options = {}) {
         out(args,`reviews ${mode}: ${r.created?.length ?? r.items?.length ?? r.selected_item_ids?.length ?? r.results?.length ?? 1} item(s)${args.write?' written':' (dry run)'}`,r);
         break;
       }
+      case 'schedules': {
+        if(args._[0]!=='run') throw new Error('usage: citable schedules run <schedule-id> [--ref-date YYYY-MM-DD]');
+        const r=await runSchedule(root,{scheduleId:args._[1],refDate:args.refDate});
+        out(args,`schedule ${r.schedule_execution.schedule_id}: audit ${r.runId}\nEvidence package: ${r.dir}\nExecution record: ${r.execution_file}`,r);
+        break;
+      }
+      case 'project': {
+        if(args._[0]!=='github') throw new Error('usage: citable project github <run-id>');
+        const r=projectGithub(root,{runId:args._[1]});
+        out(args,`project github ${r.source_run_id}: ${r.annotations.length} annotation(s)\nProjection: ${path.join(r.dir,'annotations.json')}`,r);
+        break;
+      }
       case 'self-upgrade': {
         const output = await selfUpgradeCommand(argv.slice(1));
         console.log(output);

package/src/commands/compareSnapshots.js

@@ -27,6 +27,16 @@ export function compareSnapshots(root, { runA, runB } = {}) {
   };
   const a = load(runA);
   const b = load(runB);
+  const changedKeys = (left = {}, right = {}) => [...new Set([...Object.keys(left), ...Object.keys(right)])].filter((key) => left[key] !== right[key]);
+  const changeDimensions = {
+    resource_changed: changedKeys(a.manifest.input_hashes, b.manifest.input_hashes),
+    evidence_artifacts_changed: changedKeys(a.manifest.output_hashes, b.manifest.output_hashes),
+    detector_set_changed: JSON.stringify(a.manifest.detectors_run) !== JSON.stringify(b.manifest.detectors_run),
+    configuration_changed: a.manifest.configuration_hash !== b.manifest.configuration_hash,
+    observation_method_changed: a.manifest.command !== b.manifest.command || JSON.stringify(a.manifest.argv) !== JSON.stringify(b.manifest.argv) || a.manifest.target?.kind !== b.manifest.target?.kind,
+    tool_changed: a.manifest.tool_version !== b.manifest.tool_version,
+    external_system_may_have_changed: a.manifest.target?.kind === 'url' || b.manifest.target?.kind === 'url',
+  };
   const key = (f) => `${f.detector_id}|${f.subject.identifier}|${f.observation.summary}`;
   const aKeys = new Map(a.findings.map((f) => [key(f), f]));
   const bKeys = new Map(b.findings.map((f) => [key(f), f]));
@@ -38,6 +48,11 @@ export function compareSnapshots(root, { runA, runB } = {}) {
     baseline_timestamp: a.manifest.timestamp,
     comparison_timestamp: b.manifest.timestamp,
     regressions, resolved, persisting,
+    comparability: {
+      comparable: !changeDimensions.detector_set_changed && !changeDimensions.configuration_changed && !changeDimensions.observation_method_changed && !changeDimensions.tool_changed,
+      change_dimensions: changeDimensions,
+      limitation: 'These dimensions identify observed differences between run envelopes; they do not establish what caused a finding change.',
+    },
     summary: {
       new_findings: regressions.length,
       resolved_findings: resolved.length,

package/src/commands/delivery.js

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { audit } from './audit.js';
+import { loadRegistries } from '../registries/index.js';
+import { readJson, sha256, writeJson, nowIso } from '../shared/io.js';
+
+const PKG = readJson(path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../package.json'));
+
+export async function runSchedule(root, { scheduleId, refDate } = {}) {
+  const { registries, problems } = loadRegistries(root);
+  if (problems.length) throw new Error(`registry validation failed: ${problems.join('; ')}`);
+  const schedule = registries.schedules.entries.find((item) => item.schedule_id === scheduleId);
+  if (!schedule) throw new Error(`schedule not found: ${scheduleId}`);
+  if (schedule.status !== 'active') throw new Error(`schedule ${scheduleId} is ${schedule.status}`);
+  if (schedule.expected_tool_version !== PKG.version) throw new Error(`schedule ${scheduleId} expects Citable ${schedule.expected_tool_version}, current version is ${PKG.version}`);
+  const result = await audit(root, { target: schedule.audit.target, scope: schedule.audit.scope, baseUrl: schedule.audit.base_url, refDate });
+  const execution = { schedule_id: scheduleId, cron: schedule.cron, owner: schedule.owner, executed_at: nowIso(), run_id: result.runId, manifest_hash: sha256(fs.readFileSync(path.join(result.dir, 'manifest.json'))), limitations: schedule.limitations };
+  const executionFile = path.join(root, '.citable', 'schedule-executions', `${result.runId}.json`);
+  writeJson(executionFile, execution);
+  return { ...result, schedule_execution: execution, execution_file: executionFile };
+}
+
+function annotationLevel(severity) {
+  if (['critical', 'high'].includes(severity)) return 'failure';
+  if (severity === 'medium') return 'warning';
+  return 'notice';
+}
+
+export function projectGithub(root, { runId } = {}) {
+  if (!runId) throw new Error('projection requires a source run id');
+  const runDir = path.join(root, '.citable', 'runs', runId);
+  const findingsFile = path.join(runDir, 'findings.json');
+  const manifestFile = path.join(runDir, 'manifest.json');
+  if (!fs.existsSync(findingsFile) || !fs.existsSync(manifestFile)) throw new Error(`run ${runId} is missing findings or manifest evidence`);
+  const findingsBytes = fs.readFileSync(findingsFile);
+  const manifestBytes = fs.readFileSync(manifestFile);
+  const annotations = JSON.parse(findingsBytes).map((finding) => ({
+    level: annotationLevel(finding.classification.severity),
+    title: `${finding.detector_id}: ${finding.classification.severity}`,
+    message: finding.observation.summary,
+    path: finding.subject.source_file || null,
+    line: finding.subject.source_location ? Number(String(finding.subject.source_location).match(/\d+/)?.[0]) || null : null,
+    finding_id: finding.finding_id,
+  }));
+  const projection = { source_run_id: runId, source_manifest_hash: sha256(manifestBytes), source_findings_hash: sha256(findingsBytes), generated_at: nowIso(), projection: 'github-check-annotations', authoritative: false, annotations };
+  const dir = path.join(root, '.citable', 'projections', 'github', runId);
+  writeJson(path.join(dir, 'annotations.json'), projection);
+  return { ...projection, dir };
+}

package/src/commands/observe.js

@@ -7,6 +7,7 @@ import path from 'node:path';
 import { parse as parseCsv } from 'csv-parse/sync';
 import { crawlerIdentity } from '../observations/crawlerIdentity.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
+import { observeMedia } from '../observations/media.js';
 
 const originOf = (value) => { try { return new URL(value).origin; } catch { return null; } };
 const words = (text) => String(text || '').trim().split(/\s+/).filter(Boolean);
@@ -289,6 +290,7 @@ export async function observe(root, mode, options = {}) {
     case 'consensus': return observeConsensus(root, options);
     case 'performance': return observePerformance(root, options);
     case 'corroboration': return observeCorroboration(root, options);
-    default: throw new Error('observe mode must be render, index, citations, logs, bing, passages, consensus, performance, or corroboration');
+    case 'media': return observeMedia(root, options);
+    default: throw new Error('observe mode must be render, index, citations, logs, bing, passages, consensus, performance, corroboration, or media');
   }
 }

package/src/observations/media.js

@@ -0,0 +1,75 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse } from 'node-html-parser';
+import { envelope, observationRun, readInput } from './common.js';
+import { loadRegistries } from '../registries/index.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+
+function resolveMediaPath(manifestFile, value) {
+  const file = path.resolve(path.dirname(manifestFile), value);
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) throw new Error(`media file not found: ${value}`);
+  return file;
+}
+
+async function pdfEvidence(item, file, artifacts) {
+  const pdfjs = await import('pdfjs-dist/legacy/build/pdf.mjs');
+  const bytes = new Uint8Array(fs.readFileSync(file));
+  const document = await pdfjs.getDocument({ data: bytes, disableWorker: true, useSystemFonts: true }).promise;
+  const metadata = await document.getMetadata().catch(() => ({ info: {}, metadata: null }));
+  const pages = [];
+  for (let number = 1; number <= document.numPages; number++) {
+    const page = await document.getPage(number);
+    const content = await page.getTextContent();
+    const text = content.items.map((entry) => entry.str).join(' ').replace(/\s+/g, ' ').trim();
+    pages.push({ page: number, text, word_count: text ? text.split(/\s+/).length : 0, anchor: `${item.source_url || file}#page=${number}` });
+  }
+  artifacts[`media/${item.media_id}/extracted.txt`] = pages.map((page) => `--- page ${page.page} ---\n${page.text}`).join('\n');
+  return envelope('media_pdf', { media_id: item.media_id, source_url: item.source_url, page_url: item.page_url, claim_ids: item.claim_ids, permission_status: item.permission_status, page_count: document.numPages, pages, metadata: metadata.info || {}, tagged: Boolean(metadata.info?.IsTagged) }, { method: 'static_analysis', source: file, raw: bytes, confidence: 'high', limitations: ['Reading order, tables, footnotes, signatures, revisions, accessibility tags, and scanned text are not fully validated.', 'Page text extraction does not establish that linked claims are supported.'] });
+}
+
+function transcriptEvidence(item, file, artifacts) {
+  const raw = fs.readFileSync(file, 'utf8');
+  const cues = raw.split(/\r?\n\r?\n/).map((block) => { const lines = block.split(/\r?\n/).filter(Boolean); const timing = lines.find((line) => line.includes('-->')) || null; const text = lines.filter((line) => line !== 'WEBVTT' && line !== timing && !/^\d+$/.test(line)).join(' ').replace(/<[^>]+>/g, '').trim(); return text ? { timing, text } : null; }).filter(Boolean);
+  const text = cues.map((cue) => cue.text).join(' ');
+  artifacts[`media/${item.media_id}/transcript.txt`] = text;
+  return envelope('media_transcript', { media_id: item.media_id, source_url: item.source_url, page_url: item.page_url, claim_ids: item.claim_ids, permission_status: item.permission_status, language: item.language || null, published_at: item.published_at || null, cues, word_count: text ? text.split(/\s+/).length : 0 }, { method: 'owner_import', source: file, raw, limitations: ['Speaker identity, transcription accuracy, timing accuracy, and media parity require human verification.', 'Transcript ingestion does not establish that linked claims are supported.'] });
+}
+
+async function imageEvidence(item, file, options) {
+  const html = fs.readFileSync(file, 'utf8');
+  const root = parse(html);
+  const images = root.querySelectorAll('img');
+  const image = item.image_src ? images.find((node) => node.getAttribute('src') === item.image_src) : images[0];
+  if (!image) return envelope('media_image', { media_id: item.media_id, image_src: item.image_src || null, page_url: item.page_url, claim_ids: item.claim_ids }, { method: 'static_analysis', source: file, raw: html, state: 'not_observed', limitations: ['No matching image was found in the supplied HTML.'] });
+  const figure = image.closest('figure');
+  const caption = figure?.querySelector('figcaption')?.text.replace(/\s+/g, ' ').trim() || null;
+  const alt = image.getAttribute('alt');
+  const nearby_text = (figure || image.parentNode)?.text?.replace(/\s+/g, ' ').trim() || null;
+  let ocr = { state: 'not_requested', text: null };
+  if (options.ocr) {
+    try { const tesseract = await import('tesseract.js'); const result = await tesseract.recognize(path.resolve(path.dirname(file), image.getAttribute('src')), item.language || 'eng'); ocr = { state: 'observed', text: result.data.text }; }
+    catch { ocr = { state: 'not_evidenced', text: null }; }
+  }
+  return envelope('media_image', { media_id: item.media_id, image_src: image.getAttribute('src'), source_url: item.source_url, page_url: item.page_url, claim_ids: item.claim_ids, permission_status: item.permission_status, alt: alt ?? null, caption, nearby_text, ocr }, { method: 'static_analysis', source: file, raw: html, state: options.ocr && ocr.state === 'not_evidenced' ? 'incomplete' : 'observed', confidence: 'high', limitations: [...(!alt && !caption ? ['Neither alt text nor a figure caption supplies textual context.'] : []), ...(ocr.state === 'not_evidenced' ? ['OCR was explicitly requested but the optional tesseract.js dependency or image resource was unavailable.'] : []), 'Alt text, captions, nearby text, and OCR do not establish semantic equivalence or claim support.'] });
+}
+
+export async function observeMedia(root, options) {
+  const input = readInput(options.input);
+  const check = validateAgainst('media-manifest.schema.json', input.value);
+  if (!check.valid) throw new Error(`media manifest violates contract: ${check.errors.join('; ')}`);
+  const { registries, problems } = loadRegistries(root);
+  if (problems.length) throw new Error(`registry validation failed: ${problems.join('; ')}`);
+  const claimIds = new Set(registries.claims.entries.map((claim) => claim.claim_id));
+  const observations = [], artifacts = {}, rawInputs = { media_manifest: input.raw };
+  for (const item of input.value.items) {
+    const unknown = item.claim_ids.filter((id) => !claimIds.has(id));
+    if (unknown.length) throw new Error(`${item.media_id} references unknown claim ids: ${unknown.join(', ')}`);
+    const file = resolveMediaPath(input.file, item.path);
+    rawInputs[`media_${item.media_id}`] = fs.readFileSync(file);
+    if (item.type === 'pdf') observations.push(await pdfEvidence(item, file, artifacts));
+    else if (item.type === 'transcript') observations.push(transcriptEvidence(item, file, artifacts));
+    else observations.push(await imageEvidence(item, file, options));
+  }
+  const incomplete = observations.filter((item) => item.state === 'incomplete').map((item) => `${item.data.media_id}: requested extraction is incomplete`);
+  return observationRun(root, 'observe media', input.file, observations, { rawInputs, artifacts, incomplete });
+}

package/src/registries/index.js

@@ -22,6 +22,7 @@ export const REGISTRY_SPECS = [
   { file: 'exceptions.yaml', kind: 'exceptions', schema: 'exception.schema.json', idField: 'exception_id' },
   { file: 'review-items.yaml', kind: 'review_items', schema: 'review-item.schema.json', idField: 'review_item_id' },
   { file: 'sampling-plans.yaml', kind: 'sampling_plans', schema: 'sampling-plan.schema.json', idField: 'sampling_plan_id' },
+  { file: 'schedules.yaml', kind: 'schedules', schema: 'schedule.schema.json', idField: 'schedule_id' },
 ];
 
 export function contextDir(root) {