@getopencrawl/cli 0.0.0-stage → 0.1.0

package/browser.mjs

@@ -0,0 +1,166 @@
+/** Explicitly scoped, read-only browser capture using an isolated OpenCrawl profile. */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { createInterface } from 'node:readline/promises';
+import { configDir } from './src/client.mjs';
+
+export function validateCaptureUrl(value) {
+  let url;
+  try { url = new URL(value); } catch { throw new Error('Browser capture needs an absolute URL.'); }
+  if (url.username || url.password) throw new Error('Browser URLs cannot contain credentials.');
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) {
+    throw new Error('Browser capture requires HTTPS, or HTTP on localhost.');
+  }
+  const mutationPath = /(?:^|\/)(?:logout|log-out|signout|sign-out|delete|remove|destroy|unsubscribe|deactivate|terminate)(?:\/|$)/i;
+  if (mutationPath.test(decodeURIComponent(url.pathname)) || [...url.searchParams.keys()].some(key => /^(action|delete|remove|logout|unsubscribe)$/i.test(key))) {
+    throw new Error('This URL appears to perform an action. Select a page that displays records.');
+  }
+  url.hash = '';
+  return url;
+}
+
+export function isReadOnlyRequest(method, postData) {
+  if (['GET', 'HEAD', 'OPTIONS'].includes(method.toUpperCase())) return true;
+  if (method.toUpperCase() !== 'POST' || !postData) return false;
+  try {
+    const payload = JSON.parse(postData);
+    const list = Array.isArray(payload) ? payload : [payload];
+    return list.length > 0 && list.every(item => typeof item.query === 'string' && /^\s*(?:#[^\n]*\n\s*)*(?:query\b|\{)/.test(item.query) && !/\bmutation\b/.test(item.query));
+  } catch { return false; }
+}
+
+async function playwrightModule() {
+  try { return await import('playwright'); }
+  catch { throw new Error('Browser capture needs the optional Playwright package. Install the CLI with optional dependencies, then run: opencrawl browser setup'); }
+}
+async function profile(name, origin) {
+  if (!/^[a-zA-Z0-9_-]{1,60}$/.test(name)) throw new Error('Choose a simple profile name using letters, digits, dashes, or underscores.');
+  const directory = path.join(configDir(), 'browser-profiles', name);
+  await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+  await fs.chmod(directory, 0o700);
+  const metadataFile = path.join(directory, 'profile.json');
+  let metadata;
+  try { metadata = JSON.parse(await fs.readFile(metadataFile, 'utf8')); }
+  catch (error) { if (error.code !== 'ENOENT') throw new Error('The OpenCrawl browser profile is invalid. Choose a new profile name.'); }
+  if (metadata && metadata.origin !== origin) throw new Error(`Profile ${name} is scoped to ${metadata.origin}. Choose a separate --profile for another origin.`);
+  if (!metadata) await fs.writeFile(metadataFile, JSON.stringify({ origin, created_at: new Date().toISOString() }), { mode: 0o600 });
+  return directory;
+}
+
+export async function browserCommand(action, target, options, client, overrides = {}) {
+  if (!['setup', 'login', 'capture', 'crawl'].includes(action)) throw new Error('Use browser setup, login URL, capture URL, or crawl URL.');
+  const playwright = overrides.playwright || await playwrightModule();
+  if (action === 'setup') {
+    // Invoke Playwright's own browser installer without a shell.
+    const { spawn } = await import('node:child_process');
+    const { createRequire } = await import('node:module');
+    const require = createRequire(import.meta.url);
+    const entry = path.join(path.dirname(require.resolve('playwright/package.json')), 'cli.js');
+    await new Promise((resolve, reject) => {
+      const child = spawn(process.execPath, [entry, 'install', 'chromium'], { stdio: 'inherit' });
+      child.once('error', reject); child.once('exit', code => code === 0 ? resolve() : reject(new Error('Browser installation failed.')));
+    });
+    return { installed: 'chromium' };
+  }
+  const selected = validateCaptureUrl(target);
+  const directory = await profile(options.profile || 'default', selected.origin);
+  const maxPages = action === 'crawl' ? Number(options['max-pages'] || 10) : 1;
+  if (!Number.isInteger(maxPages) || maxPages < 1 || maxPages > 100) throw new Error('--max-pages must be between 1 and 100.');
+  const prefix = options['path-prefix'] || (selected.pathname.endsWith('/') ? selected.pathname : selected.pathname.slice(0, selected.pathname.lastIndexOf('/') + 1));
+  if (!prefix.startsWith('/')) throw new Error('--path-prefix must start with /.');
+  const inScope = value => {
+    try { const url = validateCaptureUrl(value); return url.origin === selected.origin && (action !== 'crawl' || url.pathname.startsWith(prefix)); }
+    catch { return false; }
+  };
+  const queue = [selected.href];
+  if (options.urls) {
+    if (action !== 'capture') throw new Error('--urls can be used with browser capture only.');
+    const content = await fs.readFile(path.resolve(options.urls), 'utf8');
+    let urls;
+    try { urls = JSON.parse(content); } catch { urls = content.split('\n').map(line => line.trim()).filter(Boolean); }
+    if (!Array.isArray(urls) || urls.length > 100 || !urls.every(url => typeof url === 'string' && inScope(url))) {
+      throw new Error('--urls must contain at most 100 explicit page URLs on the selected origin.');
+    }
+    queue.push(...urls);
+  }
+  let context;
+  try {
+    context = await playwright.chromium.launchPersistentContext(path.join(directory, 'chromium'), {
+      headless: action === 'login' || options.interactive ? false : Boolean(options.headless), acceptDownloads: false,
+      permissions: [], viewport: { width: 1440, height: 1000 }, serviceWorkers: 'block',
+    });
+  } catch { throw new Error('Could not launch the isolated OpenCrawl browser. Run opencrawl browser setup; close any other command using this profile.'); }
+  const results = [], warnings = [], seen = new Set();
+  let blocked = 0;
+  try {
+    const page = context.pages()[0] || await context.newPage();
+    if (action === 'login' || options.interactive) {
+      await page.goto(selected.href, { waitUntil: 'domcontentloaded', timeout: 45000 });
+      process.stderr.write(`Sign in manually in the isolated OpenCrawl browser. This profile is reserved for ${selected.origin}.\n`);
+      if (!process.stdin.isTTY && !overrides.waitForLogin) throw new Error('Browser login requires an interactive terminal.');
+      if (overrides.waitForLogin) await overrides.waitForLogin(page);
+      else { const input = createInterface({ input: process.stdin, output: process.stderr }); try { await input.question('After signing in, press Enter here to save the isolated session: '); } finally { input.close(); } }
+      if (action === 'login') return { profile: options.profile || 'default', origin: selected.origin, message: 'Session saved locally. Run browser capture with the page URL you want to index.' };
+    }
+    if (!client.configured) throw new Error('Run opencrawl login before capturing pages.');
+    await context.route('**/*', async route => {
+      const request = route.request();
+      if (!isReadOnlyRequest(request.method(), request.postData())) { blocked++; await route.abort('blockedbyclient'); return; }
+      if (request.isNavigationRequest() && request.frame() === page.mainFrame() && !inScope(request.url())) { blocked++; await route.abort('blockedbyclient'); return; }
+      await route.continue();
+    });
+    // Browser popups are not part of the selected capture scope.
+    context.on('page', popup => { if (popup !== page) popup.close().catch(() => {}); });
+    while (queue.length && seen.size < (action === 'crawl' ? maxPages : 101)) {
+      const url = queue.shift();
+      if (seen.has(url) || !inScope(url)) continue;
+      seen.add(url);
+      try {
+        const response = options.interactive && page.url() === url ? null : await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 45000 });
+        if (response && response.status() >= 400) throw new Error(`HTTP ${response.status()}`);
+        await page.waitForLoadState('networkidle', { timeout: 5000 }).catch(() => {});
+        if (!inScope(page.url())) throw new Error('The page redirected outside the selected capture scope.');
+        const extracted = await page.evaluate(() => {
+          const root = (document.querySelector('main, [role="main"], article') || document.body).cloneNode(true);
+          for (const element of root.querySelectorAll('script,style,noscript,template,input,textarea,select,[contenteditable="true"],[aria-hidden="true"],[hidden]')) element.remove();
+          const blocks = new Set(['P','DIV','SECTION','ARTICLE','H1','H2','H3','H4','LI','TR','BR']);
+          const readable = node => node.nodeType === Node.TEXT_NODE ? node.textContent : [...node.childNodes].map(readable).join('') + (blocks.has(node.nodeName) ? '\n' : node.nodeName === 'TD' ? ' | ' : '');
+          const text = readable(root).replace(/\s+\n/g, '\n').replace(/[ \t]{2,}/g, ' ').trim();
+          return { title: document.title, text, links: [...document.querySelectorAll('a[href]')].map(link => link.href),
+            headings: [...document.querySelectorAll('h1,h2,h3')].map(heading => heading.textContent.trim()).filter(Boolean) };
+        });
+        if (!extracted.text || extracted.text.length < 30) throw new Error('No readable page content. Sign in with browser login, then capture the record page.');
+        const document = { title: (extracted.title || url).slice(0, 500), content: extracted.text.slice(0, 2_000_000),
+          external_id: `browser:${url}`, kind: 'web', url, visibility: 'private', metadata: {
+            capture: 'isolated-browser', origin: selected.origin, captured_at: new Date().toISOString(), headings: extracted.headings,
+            content_complete: extracted.text.length <= 2_000_000, blocked_mutating_requests: blocked,
+          } };
+        const imported = await client.request('/api/v1/documents', { method: 'POST', body: document });
+        let screenshot, ocrJob;
+        if (options.screenshots || options.ocr) {
+          const output = options.screenshots ? path.resolve(options.screenshots) : path.join(directory, 'captures'); await fs.mkdir(output, { recursive: true, mode: 0o700 });
+          screenshot = path.join(output, crypto.createHash('sha256').update(url).digest('hex').slice(0, 16) + '.png');
+          await page.screenshot({ path: screenshot, fullPage: true, mask: [page.locator('input,textarea,[contenteditable="true"]')] });
+          await fs.chmod(screenshot, 0o600);
+          if (options.ocr) {
+            const form = new FormData();
+            form.append('file', new Blob([await fs.readFile(screenshot)], { type: 'image/png' }), path.basename(screenshot));
+            form.append('visibility', 'private');
+            const uploaded = await client.request('/api/v1/uploads', { method: 'POST', body: form });
+            ocrJob = uploaded.job?.id;
+          }
+        }
+        results.push({ url, title: document.title, document_id: imported.id || imported.document?.id, characters: document.content.length, screenshot, ocr_job_id: ocrJob });
+        if (action === 'crawl') {
+          for (const link of extracted.links) {
+            if (queue.length >= 1000) break;
+            if (inScope(link)) { const canonical = validateCaptureUrl(link).href; if (!seen.has(canonical)) queue.push(canonical); }
+          }
+        }
+      } catch (error) { warnings.push({ url, error: String(error.message).split('\n')[0].slice(0, 300) }); }
+    }
+    if (blocked) warnings.push({ message: `${blocked} requests outside read-only capture scope were blocked. Some applications require additional supported read endpoints to render fully.` });
+    return { imported: results.length, pages: results, warnings, origin: selected.origin, profile: options.profile || 'default' };
+  } finally { await context.close(); }
+}

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@getopencrawl/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Search, import and bring OpenCrawl context to your agents",
+  "type": "module",
+  "bin": {
+    "opencrawl": "bin/opencrawl.mjs"
+  },
+  "exports": "./src/client.mjs",
+  "files": [
+    "bin",
+    "src",
+    "!src/**/*.test.mjs",
+    "README.md",
+    "browser.mjs"
+  ],
+  "scripts": {
+    "test": "node --test src/*.test.mjs",
+    "test:product-browser": "node --test tests/product-monitor-browser.test.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "UNLICENSED",
+  "optionalDependencies": {
+    "playwright": "^1.58.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/answer-contract.mjs

@@ -0,0 +1,112 @@
+// Validation body compiled from sdk/src/answerContract.ts; parity is checked in tests.
+// This optional reader never mutates a run or certifies whole-goal completion.
+// Keep the validation/formatter body identical across the SDK, CLI and web.
+const obj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const keys = (v, names) => Object.keys(v).length === names.length && names.every(k => Object.hasOwn(v, k));
+const int = (v, min = 0, max = Number.MAX_SAFE_INTEGER) => typeof v === 'number' && Number.isSafeInteger(v) && v >= min && v <= max;
+const text = (v, max, min = 1) => typeof v === 'string' && Array.from(v).length >= min && Array.from(v).length <= max && !/[\uD800-\uDFFF]/u.test(v) && !v.includes('\0');
+const digest = (v) => typeof v === 'string' && /^[a-f0-9]{64}$/.test(v);
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const requireValue = (ok) => { if (!ok)
+    throw new Error('Invalid optional answer assessment'); };
+const unknownNotice = (c) => `Research assessment for “${c.text}”: the saved source text used for this run does not establish an answer or its contradiction. Scope: ${c.evidence_ids.join(', ')}.`;
+const undeliveredNotice = (c) => `Research assessment for “${c.text}”: answer material was found in the saved source text, but a complete answer was not retained in this result. Scope: ${c.evidence_ids.join(', ')}.`;
+const unassessedNotice = 'Requested-answer coverage was not assessed for this run. The findings and coverage notes remain available.';
+const invalidNotice = 'Requested-answer assessment could not be validated for this run. The findings and coverage notes remain available.';
+const reasons = [null, 'component_contract_invalid', 'component_review_empty', 'goal_representation_bound', 'optional_input_bound', 'optional_output_bound', 'input_binding_invalid', 'review_skipped', 'no_evidence', 'legacy_receipt'];
+function notice(c) { return c.status === 'source_scoped_unknown_assessment' ? unknownNotice(c) : c.status === 'available_but_not_delivered' ? undeliveredNotice(c) : null; }
+export function readAnswerContract(run, hash) {
+    if (!Object.hasOwn(run.usage, 'answer_contract'))
+        return { state: 'absent', contract: null, notices: [] };
+    try {
+        const value = run.usage.answer_contract;
+        requireValue(new TextEncoder().encode(JSON.stringify(run.usage)).length <= 16384);
+        requireValue(obj(value));
+        const v = value;
+        requireValue(v.version === 1 && v.inventory === 'nonexhaustive' && v.whole_request_completeness === 'not_certified');
+        if (keys(v, ['version', 'state', 'reason', 'inventory', 'whole_request_completeness', 'components_omitted'])) {
+            requireValue(v.state === 'unassessed' && v.reason === 'optional_output_bound' && int(v.components_omitted, 0, 8));
+            return { state: 'unassessed', contract: structuredClone(v), notices: [{ id: 'unassessed', text: unassessedNotice }] };
+        }
+        requireValue(keys(v, ['version', 'state', 'reason', 'scope', 'source_scope', 'inventory', 'whole_request_completeness', 'goal_sha256', 'components', 'notice_components_omitted', 'gap_notice']));
+        requireValue(['assessed_nonexhaustive', 'unassessed'].includes(v.state) && reasons.includes(v.reason) && v.scope === 'admitted_retained_windows_only' && digest(v.goal_sha256));
+        requireValue(Array.isArray(v.source_scope) && v.source_scope.length <= 20 && Array.isArray(v.components) && v.components.length <= 8);
+        const scopes = new Map();
+        for (const s of v.source_scope) {
+            requireValue(obj(s) && keys(s, ['evidence_id', 'source_sha256', 'window_text_sha256', 'window_chars', 'source_kind', ...(s.source_kind === 'web_page' ? ['page'] : [])]));
+            requireValue(text(s.evidence_id, 80) && s.evidence_id.trim() === s.evidence_id && !/[\u0000-\u0020\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/u.test(s.evidence_id) && !scopes.has(s.evidence_id) && digest(s.source_sha256) && digest(s.window_text_sha256) && int(s.window_chars, 1, 16000) && ['indexed', 'web_page'].includes(s.source_kind));
+            if (s.source_kind === 'web_page') {
+                const p = s.page;
+                requireValue(obj(p) && keys(p, ['body_sha256', 'start', 'end', 'total_chars']) && digest(p.body_sha256) && int(p.start, 0, 131071) && int(p.end, 1, 131072) && int(p.total_chars, 1, 131072) && p.start < p.end && p.end <= p.total_chars && p.end - p.start === s.window_chars);
+            }
+            scopes.set(s.evidence_id, s);
+        }
+        // Available citations must agree, but uncited scope is retained too. No new
+        // source fetch or mutable agent.goal is substituted for the original run.
+        for (const f of run.findings)
+            for (const cite of f.citations) {
+                const s = scopes.get(cite.id);
+                requireValue(s && s.window_text_sha256 === cite.body_sha256 && s.source_kind === cite.source_kind);
+                if (s?.source_kind === 'web_page')
+                    requireValue(cite.page && ['body_sha256', 'start', 'end', 'total_chars'].every(k => s.page[k] === cite.page[k]));
+            }
+        requireValue(v.state === 'unassessed' ? (v.components.length === 0 && v.reason !== null) : (v.components.length > 0 && v.reason === null));
+        const ids = new Set(), spans = [], eligible = [];
+        const allIds = [...scopes.keys()];
+        for (const c of v.components) {
+            requireValue(obj(c) && keys(c, ['component_id', 'start', 'end', 'text', 'status', 'reason', 'fact_refs', 'evidence_ids', 'source_state']));
+            requireValue(typeof c.component_id === 'string' && /^[CM][1-8]$/.test(c.component_id) && !ids.has(c.component_id));
+            ids.add(c.component_id);
+            requireValue(int(c.start, 0, 3999) && int(c.end, 1, 4000) && text(c.text, 256) && c.text.trim() && c.end - c.start === Array.from(c.text).length);
+            requireValue(['literal_answer', 'literal_negative_answer', 'source_scoped_unknown_assessment', 'available_but_not_delivered', 'unassessed'].includes(c.status));
+            requireValue([null, 'linked_finding_rejected', 'request_anchor_not_meaningful', 'review_unassessed'].includes(c.reason) && ['supported', 'explicitly_contradicted', 'not_established', 'unassessed'].includes(c.source_state));
+            requireValue(Array.isArray(c.evidence_ids) && c.evidence_ids.length <= 20 && same(c.evidence_ids, allIds.filter(id => c.evidence_ids.includes(id))) && Array.isArray(c.fact_refs) && c.fact_refs.length <= 10);
+            const refIds = new Set(), ownIds = new Set();
+            for (const r of c.fact_refs) {
+                requireValue(obj(r) && keys(r, ['finding_id', 'field', 'qualifier_ordinal', 'literal_text_sha256']) && digest(r.literal_text_sha256));
+                const f = run.findings.find(f => f.id === r.finding_id), key = JSON.stringify([r.finding_id, r.field, r.qualifier_ordinal]);
+                requireValue(f && !refIds.has(key) && ['claim', 'qualifier'].includes(r.field) && int(r.qualifier_ordinal, r.field === 'claim' ? 0 : 1, r.field === 'claim' ? 0 : f?.qualifiers.length));
+                refIds.add(key);
+                const literal = r.field === 'claim' ? f.claim : f.qualifiers[r.qualifier_ordinal - 1];
+                requireValue(hash(literal) === r.literal_text_sha256);
+                f.citations.forEach(cite => ownIds.add(cite.id));
+            }
+            if (c.status === 'unassessed')
+                requireValue(c.source_state === 'unassessed' && ['request_anchor_not_meaningful', 'review_unassessed'].includes(c.reason) && !c.fact_refs.length && !c.evidence_ids.length);
+            else if (c.status === 'source_scoped_unknown_assessment')
+                requireValue(c.source_state === 'not_established' && c.reason === null && !c.fact_refs.length && allIds.length > 0 && same(c.evidence_ids, allIds));
+            else {
+                requireValue(['supported', 'explicitly_contradicted'].includes(c.source_state) && c.evidence_ids.length > 0);
+                if (c.status === 'available_but_not_delivered')
+                    requireValue(c.reason === null || c.reason === 'linked_finding_rejected');
+                else
+                    requireValue(c.reason === null && c.fact_refs.length > 0 && c.status === (c.source_state === 'supported' ? 'literal_answer' : 'literal_negative_answer') && same(c.evidence_ids, allIds.filter(id => ownIds.has(id))));
+            }
+            if (c.reason !== 'request_anchor_not_meaningful') {
+                requireValue(spans.every(p => p.text !== c.text && (p.end <= c.start || p.start >= c.end)));
+                spans.push(c);
+            }
+            if (notice(c))
+                eligible.push(c);
+        }
+        requireValue(int(v.notice_components_omitted, 0, eligible.length));
+        let delivered = [];
+        if (v.gap_notice !== null) {
+            const g = v.gap_notice;
+            requireValue(obj(g) && keys(g, ['index', 'sha256', 'component_ids']) && int(g.index, 0, run.gaps.length - 1) && g.index === run.gaps.length - 1 && digest(g.sha256) && hash(run.gaps[g.index]) === g.sha256);
+            requireValue(Array.isArray(g.component_ids) && g.component_ids.length > 0 && same(g.component_ids, eligible.filter(c => g.component_ids.includes(c.component_id)).map(c => c.component_id)));
+            const suffix = ' ' + eligible.filter(c => g.component_ids.includes(c.component_id)).map(c => notice(c)).join(' ');
+            requireValue(run.gaps[g.index].endsWith(suffix));
+            delivered = g.component_ids;
+        }
+        requireValue(v.notice_components_omitted === eligible.length - delivered.length);
+        const notices = v.state === 'unassessed' ? [{ id: 'unassessed', text: unassessedNotice }] : v.components.flatMap((c) => {
+            const n = notice(c);
+            return n && !delivered.includes(c.component_id) ? [{ id: c.component_id, text: n }] : c.status === 'unassessed' ? [{ id: c.component_id, text: `Research assessment for “${c.text}”: requested-answer coverage was not assessed.` }] : [];
+        });
+        return { state: v.state, contract: structuredClone(v), notices };
+    }
+    catch {
+        return { state: 'invalid', contract: null, notices: [{ id: 'invalid', text: invalidNotice }] };
+    }
+}

package/src/answer-view.mjs

@@ -0,0 +1,118 @@
+// Validation body compiled from sdk/src/answerView.ts; parity is checked in tests.
+const obj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const keys = (v, names) => Object.keys(v).length === names.length && names.every(k => Object.hasOwn(v, k));
+const need = (ok) => { if (!ok)
+    throw new Error('Invalid optional concise answer'); };
+const digest = (v) => typeof v === 'string' && /^[a-f0-9]{64}$/.test(v);
+const refKey = (r) => JSON.stringify([r.finding_id, r.field, r.qualifier_ordinal, r.literal_text_sha256]);
+const empty = (state) => ({ state, view: null, sections: [] });
+const byteLength = (text) => new TextEncoder().encode(text).length;
+/** Python's sorted-key, compact, ensure_ascii=False JSON for bounded public data.
+ * Literal strings are not normalized. Reject lossy JSON values and lone surrogates.
+ */
+export function canonicalAnswerJson(value) {
+    let nodes = 0;
+    const scalar = (text) => { need(!/[\uD800-\uDFFF]/u.test(text)); return JSON.stringify(text); };
+    const compare = (a, b) => { const x = Array.from(a), y = Array.from(b); for (let i = 0; i < Math.min(x.length, y.length); i++) {
+        const d = x[i].codePointAt(0) - y[i].codePointAt(0);
+        if (d)
+            return d;
+    } return x.length - y.length; };
+    const encode = (v, depth) => {
+        need(++nodes <= 8192 && depth <= 24);
+        if (v === null)
+            return 'null';
+        if (typeof v === 'string')
+            return scalar(v);
+        if (typeof v === 'boolean')
+            return v ? 'true' : 'false';
+        if (typeof v === 'number') {
+            need(Number.isSafeInteger(v) && !Object.is(v, -0));
+            return String(v);
+        }
+        if (Array.isArray(v))
+            return '[' + Array.from(v, item => encode(item, depth + 1)).join(',') + ']';
+        need(obj(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null));
+        return '{' + Object.keys(v).sort(compare).map(k => scalar(k) + ':' + encode(v[k], depth + 1)).join(',') + '}';
+    };
+    const result = encode(value, 0);
+    need(byteLength(result) <= 65536);
+    return result;
+}
+function omission(c, reason) {
+    if (reason === 'source_scoped_unknown')
+        return 'Not established in the saved sources for this part.';
+    if (reason === 'answer_not_delivered')
+        return 'Answer material was found in the saved source text, but a complete answer was not retained in this result.';
+    return c.status === 'unassessed' ? 'Review the exact evidence for this part. Requested-answer coverage was not assessed.' : 'Review the exact evidence for this part. Concise prose was not retained.';
+}
+/** The wrappers supply the existing validated contract. Optional failure never
+ * changes a run, its findings/gaps, or the original contract's coverage notices.
+ */
+export function readAnswerView(run, contractView, hash) {
+    if (!Object.hasOwn(run.usage, 'answer_view'))
+        return empty('absent');
+    try {
+        need(contractView.state === 'assessed_nonexhaustive' && contractView.contract !== null);
+        const contract = contractView.contract, value = run.usage.answer_view;
+        need(obj(value));
+        const v = value;
+        need(keys(v, ['version', 'goal_sha256', 'answer_contract_sha256', 'findings_sha256', 'sections', 'omitted']) && v.version === 1);
+        need(byteLength(canonicalAnswerJson(v)) <= 8192 && byteLength(canonicalAnswerJson(run.usage)) <= 16384);
+        need(run.findings.length <= 5 && run.findings.every(f => f.qualifiers.length <= 5 && [f.claim, ...f.qualifiers].every(t => typeof t === 'string' && Array.from(t).length <= 1500)));
+        need(digest(v.goal_sha256) && v.goal_sha256 === contract.goal_sha256 && digest(v.answer_contract_sha256) && digest(v.findings_sha256));
+        need(hash(canonicalAnswerJson(run.usage.answer_contract)) === v.answer_contract_sha256 && hash(canonicalAnswerJson(run.findings)) === v.findings_sha256);
+        need(Array.isArray(v.sections) && v.sections.length <= 8 && Array.isArray(v.omitted) && v.omitted.length <= 8);
+        const ordered = [...contract.components].sort((a, b) => a.start - b.start || a.end - b.end), byId = new Map(ordered.map(c => [c.component_id, c]));
+        const sections = new Map(), omitted = new Map();
+        let total = 0;
+        for (const s of v.sections) {
+            need(obj(s) && keys(s, ['component_id', 'assertions']) && !sections.has(s.component_id));
+            const c = byId.get(s.component_id);
+            need(c && ['literal_answer', 'literal_negative_answer'].includes(c.status));
+            need(Array.isArray(s.assertions) && s.assertions.length >= 1 && s.assertions.length <= 2);
+            const expected = new Set(c.fact_refs.map(refKey)), actual = new Set();
+            for (const a of s.assertions) {
+                need(obj(a) && keys(a, ['text', 'fact_refs']) && typeof a.text === 'string' && a.text === a.text.trim() && a.text.length > 0 && !/\p{C}/u.test(a.text));
+                total += Array.from(a.text).length;
+                need(total <= 1800);
+                need(Array.isArray(a.fact_refs) && a.fact_refs.length >= 1 && a.fact_refs.length <= 10);
+                const own = new Set();
+                for (const r of a.fact_refs) {
+                    need(obj(r) && keys(r, ['finding_id', 'field', 'qualifier_ordinal', 'literal_text_sha256']));
+                    const finding = run.findings.find(f => f.id === r.finding_id);
+                    need(finding && ['claim', 'qualifier'].includes(r.field) && Number.isSafeInteger(r.qualifier_ordinal) && digest(r.literal_text_sha256));
+                    need(r.field === 'claim' ? r.qualifier_ordinal === 0 : r.qualifier_ordinal >= 1 && r.qualifier_ordinal <= finding.qualifiers.length);
+                    const literal = r.field === 'claim' ? finding.claim : finding.qualifiers[r.qualifier_ordinal - 1];
+                    need(typeof literal === 'string' && hash(literal) === r.literal_text_sha256);
+                    const key = refKey(r);
+                    need(!own.has(key));
+                    own.add(key);
+                    actual.add(key);
+                }
+            }
+            // Extra reviewed, retained fields may carry necessary context. They never
+            // substitute for a required component field or a missing qualification.
+            need([...expected].every(key => actual.has(key)));
+            sections.set(s.component_id, s.assertions);
+        }
+        for (const o of v.omitted) {
+            need(obj(o) && keys(o, ['component_id', 'reason']) && !sections.has(o.component_id) && !omitted.has(o.component_id));
+            const c = byId.get(o.component_id);
+            need(c);
+            const allowed = c.status === 'source_scoped_unknown_assessment' ? ['source_scoped_unknown'] : c.status === 'available_but_not_delivered' ? ['answer_not_delivered'] : c.status === 'unassessed' ? ['unassessed'] : ['prose_not_supplied', 'prose_review_failed', 'fact_binding_failed'];
+            need(allowed.includes(o.reason));
+            omitted.set(o.component_id, o.reason);
+        }
+        need(sections.size + omitted.size === ordered.length);
+        need(JSON.stringify([...sections.keys()]) === JSON.stringify(ordered.filter(c => sections.has(c.component_id)).map(c => c.component_id)));
+        need(JSON.stringify([...omitted.keys()]) === JSON.stringify(ordered.filter(c => omitted.has(c.component_id)).map(c => c.component_id)));
+        return { state: 'valid', view: structuredClone(v), sections: structuredClone(ordered.map(component => {
+                const reason = omitted.get(component.component_id) ?? null;
+                return { component, assertions: sections.get(component.component_id) ?? [], omission_reason: reason, notice: reason === null ? null : omission(component, reason) };
+            })) };
+    }
+    catch {
+        return empty('invalid');
+    }
+}