@volter/twin-catalog 0.2.2

package/lib/browse.mjs

@@ -0,0 +1,123 @@
+// Read-only discovery over a published index. Never resolve or import candidate packages.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { digest, loadIndex, read, requireThat, selection, stable, submissionId, validateIndex } from './model.mjs';
+
+const textOrder = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+const releaseKey = (v) => `${v.package}@${v.version}`;
+
+function repositoryOf(pkg) {
+  const value = typeof pkg.repository === 'string' ? pkg.repository : pkg.repository?.url;
+  const match = /^git\+https:\/\/github\.com\/([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value ?? '') ??
+    /^https:\/\/github\.com\/([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value ?? '');
+  requireThat(match, 'catalog package must name its GitHub repository');
+  return `https://github.com/${match[1]}`;
+}
+
+function reportFor(root, version) {
+  const evidence = version.evidence;
+  if (!evidence?.reportSha256) return null;
+  requireThat(/^[a-f0-9]{64}$/.test(evidence.submission) && /^[a-f0-9]{64}$/.test(evidence.reportSha256), 'invalid report identity');
+  const path = `evidence/${evidence.submission}.json`;
+  requireThat(evidence.reportPath === path && existsSync(join(root, path)), `${releaseKey(version)}: bound report is missing`);
+  const envelope = read(join(root, path));
+  requireThat(digest(envelope) === evidence.reportSha256, `${releaseKey(version)}: report checksum differs`);
+  const input = envelope.input;
+  const submission = input?.submission;
+  requireThat(envelope.inputSha256 === digest(input) && submission && submissionId(submission) === evidence.submission,
+    `${releaseKey(version)}: report input identity differs`);
+  requireThat(submission.vendor === version.vendor && submission.package === version.package && submission.version === version.version &&
+    submission.source === version.source && submission.integrity === version.integrity, `${releaseKey(version)}: report release differs`);
+  const report = envelope.report;
+  requireThat(envelope.status === 'ready' && report?.ready === true && report.vendor === version.vendor &&
+    report.package === version.package && report.version === version.version, `${releaseKey(version)}: report is not release readiness`);
+  return { envelope, report };
+}
+
+/** Load and project an installed index. integrity is caller-retained install evidence, not computed here. */
+export function browse(root, { vendor, package: packageName, integrity = null } = {}) {
+  const pkg = read(join(root, 'package.json'));
+  const catalog = read(join(root, 'catalog.json'));
+  const index = validateIndex(loadIndex(root));
+  requireThat(catalog.schemaVersion === 1 && Array.isArray(catalog.versions), 'unsupported catalog snapshot');
+  requireThat(/^[a-f0-9]{40}$/.test(catalog.sourceCommit) && /^[a-f0-9]{64}$/.test(catalog.digest), 'invalid snapshot identity');
+  requireThat(pkg.catalog?.sourceCommit === catalog.sourceCommit && pkg.catalog?.digest === catalog.digest, 'package/catalog identity differs');
+  requireThat(integrity === null || /^sha512-[A-Za-z0-9+/]{86}==$/.test(integrity), 'invalid retained install integrity');
+  const records = new Map();
+  const references = {};
+  for (const v of catalog.versions) {
+    requireThat(!records.has(releaseKey(v)), 'repeated catalog release');
+    records.set(releaseKey(v), v);
+    if (v.evidence) {
+      const { submission, admissionCommit, ...receipt } = v.evidence;
+      requireThat(submission === (v.submission ?? v.assessment) && admissionCommit === (v.assessmentCommit ?? v.commit), 'evidence admission identity differs');
+      if (Object.keys(receipt).length) {
+        requireThat(!references[submission] || stable(references[submission]) === stable(receipt), 'conflicting evidence references');
+        references[submission] = receipt;
+      }
+    }
+  }
+  const expected = index.vendors.flatMap((e) => e.packages.flatMap((p) => p.versions.map((v) => {
+    const id = v.submission ?? v.assessment;
+    return { vendor: e.vendor, package: p.name, source: p.source, ...v,
+      evidence: id ? { submission: id, admissionCommit: v.assessmentCommit ?? v.commit, ...(references[id] ?? {}) } : null,
+      assessed: Boolean(id) };
+  })));
+  requireThat(expected.length === records.size && expected.every((v) => stable(v) === stable(records.get(releaseKey(v)))),
+    'catalog records differ from index data');
+  const snapshotDigest = (vendors) => digest({ evidence: references, sources: index.sources, vendors,
+    recommendations: index.recommendations, revocations: index.revocations });
+  // Publication can append newly admitted vendors after the legacy vendors. Directory enumeration is alphabetical;
+  // catalog.json retains the publication order. Accept either only when its complete digest matches the snapshot.
+  const publicationOrder = new Map([...new Set(catalog.versions.map((v) => v.vendor))].map((name, at) => [name, at]));
+  const orderedVendors = [...index.vendors].sort((a, b) =>
+    (publicationOrder.get(a.vendor) ?? index.vendors.length) - (publicationOrder.get(b.vendor) ?? index.vendors.length));
+  requireThat(snapshotDigest(index.vendors) === catalog.digest || snapshotDigest(orderedVendors) === catalog.digest,
+    'catalog snapshot digest differs');
+  const repository = repositoryOf(pkg);
+  if (vendor !== undefined) requireThat(index.vendors.some((e) => e.vendor === vendor), `unknown catalog vendor: ${vendor}`);
+  if (packageName !== undefined) requireThat(index.vendors.some((e) => (vendor === undefined || e.vendor === vendor) &&
+    e.packages.some((p) => p.name === packageName)), `unknown catalog package: ${packageName}`);
+
+  const vendors = index.vendors.filter((e) => vendor === undefined || e.vendor === vendor)
+    .filter((e) => packageName === undefined || e.packages.some((p) => p.name === packageName))
+    .sort((a, b) => textOrder(a.vendor, b.vendor)).map((entry) => {
+      // Compute the choice before filtering: a package filter cannot silently change the default.
+      const { candidates, recommended, choice } = selection(index, entry);
+      const defaultRelease = choice ? { package: choice.p.name, version: choice.v.version, source: choice.p.source } : null;
+      const state = choice ? 'selected' : recommended ? 'unavailable-recommendation' : candidates.length > 1 ? 'choice-required' : 'unavailable';
+      return { vendor: entry.vendor, recommendation: recommended ?? null, selection: { state, default: defaultRelease },
+        implementations: entry.packages.filter((p) => packageName === undefined || p.name === packageName)
+          .sort((a, b) => textOrder(a.name, b.name)).map((p) => {
+            const source = index.sources.find((s) => s.name === p.source);
+            const sourceUrl = `https://github.com/${source.repository}`;
+            return { package: p.name, source: { ...source, url: sourceUrl,
+              workflowUrl: `${sourceUrl}/blob/HEAD/.github/workflows/${source.workflow ?? 'release.yml'}` },
+              versions: p.versions.map((v) => {
+                const record = records.get(`${p.name}@${v.version}`);
+                const bound = reportFor(root, record);
+                const revoked = index.revocations.find((r) => r.package === p.name && r.version === v.version);
+                const selectable = v.status === 'live' && !v.version.includes('-') && !revoked;
+                const quick = bound?.report.quick, browser = bound?.report.browser;
+                return { ...v, revoked: revoked ? { reason: revoked.reason } : null, selectable: Boolean(selectable),
+                  default: choice?.p.name === p.name && choice.v.version === v.version,
+                  assessment: { recorded: record.assessed, available: Boolean(bound), evidence: record.evidence,
+                    input: bound ? { repository: bound.envelope.input.repository, pullRequest: bound.envelope.input.pullRequest,
+                      head: bound.envelope.input.head, base: bound.envelope.input.base, image: bound.envelope.image,
+                      workflow: bound.envelope.workflow, tools: bound.envelope.input.policy?.tools ?? null } : null },
+                  measurements: bound ? {
+                    scope: quick?.scope ?? null, surface: quick?.surface ?? null,
+                    operationCoverage: quick?.operationCoverage ?? null, servedOperations: quick?.servedOperations ?? null,
+                    steps: quick?.steps ?? null, answered: quick?.answered ?? null, failures: quick?.failures ?? null,
+                    replay: quick?.replay ?? null, conformance: bound.report.conformance ?? null,
+                    browser: browser?.measured === true ? browser : null,
+                    codeCoverage: quick?.codeCoverage ?? null, stateTransitionCoverage: quick?.stateTransitionCoverage ?? null,
+                    domCoverage: browser?.domCoverage ?? null, comparison: bound.report.comparison ?? null } : null };
+              }) };
+          }) };
+    });
+  return { schemaVersion: 1, snapshot: { package: pkg.name, version: pkg.version, integrity,
+    sourceCommit: catalog.sourceCommit, digest: catalog.digest },
+    contribution: { repository, registrationUrl: `${repository}/edit/main/sources.json`,
+      pullRequestsUrl: `${repository}/pulls`, guideUrl: `${repository}/blob/${catalog.sourceCommit}/docs/contributing.md` }, vendors };
+}

package/lib/evidence.mjs

@@ -0,0 +1,74 @@
+// Trusted controller receipts outlive workflow-artifact retention. No candidate code is imported here.
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { digest, requireThat, stable, submissionId } from './model.mjs';
+
+export function validateEvidence(envelope, proof, repository) {
+  requireThat(digest(envelope) === proof.reportSha256, 'evidence digest differs from successful readiness receipt');
+  requireThat(envelope.status === 'ready' && envelope.report?.ready === true, 'evidence is not successful package readiness');
+  requireThat(envelope.input?.repository === repository && envelope.input?.pullRequest === proof.pullRequest && envelope.input?.head === proof.head && envelope.input?.base === proof.base, 'evidence PR identity differs');
+  requireThat(stable(envelope.input.submission) === stable(proof.submission), 'evidence artifact identity differs');
+  requireThat(envelope.inputSha256 === digest(envelope.input) && envelope.dependencyLock?.packages && envelope.workflow?.repository === repository && envelope.workflow.file === 'check.yml', 'evidence input or workflow identity differs');
+  requireThat(!proof.workflow || (envelope.workflow.run === proof.workflow.run && envelope.workflow.attempt === proof.workflow.attempt), 'evidence workflow differs from bound receipt');
+  return envelope;
+}
+export async function readinessRun(proof, github) {
+  if (proof.workflow) {
+    const { run: id, attempt } = proof.workflow;
+    requireThat(Number.isSafeInteger(id) && id > 0 && Number.isSafeInteger(attempt) && attempt > 0, 'invalid readiness workflow run or attempt');
+    const run = await github.call(`actions/runs/${id}/attempts/${attempt}`);
+    requireThat(run.id === id && run.run_attempt === attempt && run.repository?.full_name === github.repository, 'readiness workflow identity differs from receipt');
+    requireThat(run.path === '.github/workflows/check.yml' && ['pull_request_target', 'workflow_dispatch'].includes(run.event), 'evidence did not come from the trusted readiness workflow');
+    requireThat(run.status === 'completed' && run.conclusion === 'success', 'readiness workflow attempt did not succeed');
+    requireThat(run.head_sha === (run.event === 'workflow_dispatch' ? proof.base : proof.head), 'readiness workflow source commit differs from bound input');
+    return run;
+  }
+  const url = new URL(proof.check.details_url);
+  requireThat(url.origin === 'https://github.com', 'readiness evidence is not a GitHub run');
+  const prefix = `/${github.repository}/actions/runs/`;
+  const runId = url.pathname.startsWith(prefix) ? url.pathname.slice(prefix.length) : '';
+  let run;
+  if (/^[0-9]+$/.test(runId)) run = await github.call(`actions/runs/${runId}`);
+  else {
+    requireThat(url.pathname === `/${github.repository}/runs/${proof.check.id}` && Number.isSafeInteger(proof.check.check_suite?.id), 'readiness evidence run belongs to a different repository');
+    const suite = proof.check.check_suite.id;
+    const result = await github.call(`actions/runs?check_suite_id=${suite}&per_page=100`);
+    const matches = result.workflow_runs.filter((r) => r.check_suite_id === suite && r.head_sha === proof.head && r.path === '.github/workflows/check.yml');
+    requireThat(matches.length === 1, 'readiness check has no unique matching workflow run');
+    run = matches[0];
+  }
+  requireThat(run.path === '.github/workflows/check.yml' && ['pull_request_target', 'workflow_dispatch'].includes(run.event), 'evidence did not come from the trusted readiness workflow');
+  return run;
+}
+export async function persistEvidence(proofs, github) {
+  const receipts = {};
+  for (const proof of proofs) {
+    const id = submissionId(proof.submission), tag = `evidence-${id}-${proof.reportSha256}`;
+    let release = await github.optional(`releases/tags/${tag}`);
+    let asset = release?.assets.find((a) => a.name === 'report.json');
+    let envelope;
+    if (asset) envelope = JSON.parse((await github.download(`releases/assets/${asset.id}`)).toString('utf8'));
+    else {
+      const run = await readinessRun(proof, github);
+      const artifacts = await github.call(`actions/runs/${run.id}/artifacts?per_page=100`);
+      const artifact = artifacts.artifacts.find((a) => a.name === `catalog-assessment-${run.id}-${run.run_attempt}` && !a.expired);
+      requireThat(artifact, 'readiness report expired or missing; reassess the current PR before admission');
+      const temp = mkdtempSync(join(tmpdir(), 'catalog-evidence-')), file = join(temp, 'evidence.zip');
+      writeFileSync(file, await github.download(`actions/artifacts/${artifact.id}/zip`));
+      // Read one member to stdout; never extract paths supplied in an archive.
+      const data = spawnSync('unzip', ['-p', file, 'report.json'], { encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 });
+      requireThat(data.status === 0, 'readiness artifact contains no readable report');
+      envelope = JSON.parse(data.stdout);
+      requireThat(envelope.workflow?.run === run.id && envelope.workflow?.attempt === run.run_attempt, 'evidence workflow differs from artifact source');
+      validateEvidence(envelope, proof, github.repository);
+      if (!release) release = await github.call('releases', 'POST', { tag_name: tag, target_commitish: proof.commit, name: `Assessment ${proof.submission.package}@${proof.submission.version}`, body: `Readiness report SHA-256: ${proof.reportSha256}\nAdmission PR: #${proof.pullRequest}`, draft: false, prerelease: true });
+      asset = await github.upload(release.upload_url, 'report.json', Buffer.from(`${JSON.stringify(envelope, null, 2)}\n`));
+    }
+    validateEvidence(envelope, proof, github.repository);
+    // The resolved dependency lock is retained in the report identity; workflow diagnostics are supplementary.
+    receipts[id] = { pullRequest: proof.pullRequest, url: release.html_url, reportSha256: proof.reportSha256, reportPath: `evidence/${id}.json`, ...(proof.moderation ? { moderation: proof.moderation } : {}), envelope };
+  }
+  return receipts;
+}

package/lib/github.mjs

@@ -0,0 +1,88 @@
+import { requireThat } from './model.mjs';
+
+export class GitHub {
+  constructor(repository, token, fetcher = fetch) {
+    requireThat(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository), 'invalid repository');
+    requireThat(token, 'GitHub token required for repository automation');
+    this.repository = repository; this.token = token; this.fetcher = fetcher;
+  }
+  async call(path, method = 'GET', body) {
+    const url = `https://api.github.com/repos/${this.repository}/${path}`;
+    const options = { method, headers: { authorization: `Bearer ${this.token}`, accept: 'application/vnd.github+json', 'x-github-api-version': '2022-11-28' }, ...(body === undefined ? {} : { body: JSON.stringify(body) }) };
+    let r;
+    for (let attempt = 0; ; attempt++) {
+      try { r = await this.fetcher(url, options); break; }
+      catch (error) {
+        // Both sandbox attempts retained ready evidence but failed on the post-evaluation read
+        // (Actions 37313751170, attempts 1 and 2). Retry the read, never a potentially applied write.
+        if (method === 'GET' && attempt === 0) continue;
+        const code = error.cause?.code ?? error.code ?? 'unknown';
+        throw new Error(`GitHub ${method} ${path}: transport failed (${code})`, { cause: error });
+      }
+    }
+    if (!r.ok) { const error = new Error(`GitHub ${method} ${path}: HTTP ${r.status}`); error.status = r.status; throw error; }
+    return r.status === 204 ? null : r.json();
+  }
+  async optional(path) {
+    try { return await this.call(path); } catch (error) { if (error.status === 404) return null; throw error; }
+  }
+  async download(path) {
+    const accept = /^releases\/assets\/\d+$/.test(path) ? 'application/octet-stream' : 'application/vnd.github+json';
+    const response = await this.fetcher(`https://api.github.com/repos/${this.repository}/${path}`, { headers: { authorization: `Bearer ${this.token}`, accept, 'x-github-api-version': '2022-11-28' } });
+    requireThat(response.ok, `GitHub download ${path}: HTTP ${response.status}`);
+    return Buffer.from(await response.arrayBuffer());
+  }
+  async upload(url, name, bytes) {
+    const target = new URL(url.replace(/\{.*$/, ''));
+    requireThat(target.origin === 'https://uploads.github.com', 'unexpected evidence upload host');
+    target.searchParams.set('name', name);
+    const response = await this.fetcher(target, { method: 'POST', headers: { authorization: `Bearer ${this.token}`, 'content-type': 'application/json', 'x-github-api-version': '2022-11-28' }, body: bytes });
+    requireThat(response.ok, `GitHub evidence upload: HTTP ${response.status}`);
+    return response.json();
+  }
+  async pages(path) {
+    const result = [];
+    for (let page = 1; ; page++) {
+      const rows = await this.call(`${path}${path.includes('?') ? '&' : '?'}per_page=100&page=${page}`);
+      requireThat(Array.isArray(rows), 'GitHub pagination expected an array');
+      result.push(...rows);
+      if (rows.length < 100) return result;
+    }
+  }
+  async content(path, ref) {
+    requireThat(/^[a-f0-9]{40}$/.test(ref), 'content must be read at an immutable commit');
+    const doc = await this.call(`contents/${path.split('/').map(encodeURIComponent).join('/')}?ref=${ref}`);
+    requireThat(doc.type === 'file' && doc.encoding === 'base64', 'expected a data file');
+    return Buffer.from(doc.content, 'base64').toString('utf8');
+  }
+}
+
+const escape = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/@/g, '@\u200b').replace(/`/g, '\\`');
+export function summary(envelope) {
+  const s = envelope.input?.submission;
+  const lines = [`Catalog: **${escape(envelope.status)}**`, '', `Head: \`${escape(envelope.input?.head ?? 'unknown')}\``, `Policy and inputs: \`${envelope.inputSha256 ?? 'not assessed'}\``];
+  if (s) lines.push(`Artifact: \`${escape(s.package)}@${escape(s.version)}\``, `Integrity: \`${s.integrity}\``);
+  if (envelope.error) lines.push('', escape(envelope.error));
+  const report = envelope.report;
+  if (report) {
+    lines.push('', `Journey: ${escape(report.quick?.answered ?? 'not measured')} answered steps; ${escape(report.quick?.failures?.length ?? 'not measured')} recorded failures.`, `Replay: ${report.quick?.replay?.equal ? 'matches' : 'failed'}.`);
+    const surface = report.quick?.surface;
+    lines.push(surface ? `Declared API surface: ${escape(surface.served)}/${escape(surface.total)} served; ${escape(surface.gap)} gaps.` : 'Declared API surface: not measured.');
+    const coverage = report.quick?.operationCoverage;
+    lines.push(coverage ? `Journey operation coverage: ${escape(coverage.exercised)}/${escape(coverage.total)} (${escape(coverage.percent.toFixed(1))}%).` : 'Journey operation coverage: not measured.');
+    lines.push(report.browser?.measured ? `Chromium: ${escape(report.browser.version)}; ${escape(report.browser.answered)} answered steps; ${escape(report.browser.failures.length)} failures; replay ${report.browser.replay.equal ? 'matches' : 'failed'}.` : `Chromium: not measured (${escape(report.browser?.reason ?? 'unknown target')}).`);
+    lines.push('Browser DOM, code-line and state-transition coverage: not measured by this quick run.');
+    for (const group of [...(report.gates ?? []), ...(report.conformance ?? [])]) for (const failure of group.failures ?? []) lines.push(`- ${escape(group.id ?? group.unit)}: ${escape(failure)}`);
+    for (const failure of report.quick?.failures ?? []) lines.push(`- ${escape(failure.step)} / ${escape(failure.beat)}: ${escape(failure.detail)}`);
+    lines.push('', escape(report.comparison?.note ?? 'Baseline comparison is in the JSON report.'));
+  }
+  lines.push('', 'An authorized maintainer merges the current head after readiness. Direct trusted accounts need no separate review; untrusted accounts also need current-head moderator approval.', 'The workflow artifacts contain the complete JSON report and diagnostics.');
+  return lines.join('\n').slice(0, 60000);
+}
+
+export async function feedback(github, number, body) {
+  const marker = '<!-- twin-catalog-readiness -->';
+  const comments = await github.pages(`issues/${number}/comments`);
+  const old = comments.find((c) => c.user?.login === 'github-actions[bot]' && c.body?.startsWith(marker));
+  return github.call(old ? `issues/comments/${old.id}` : `issues/${number}/comments`, old ? 'PATCH' : 'POST', { body: `${marker}\n${body}` });
+}

package/lib/model.mjs

@@ -0,0 +1,172 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, readdirSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const canonical = (v) => v && typeof v === 'object' ? Array.isArray(v) ? v.map(canonical) : Object.fromEntries(Object.keys(v).filter((k) => v[k] !== undefined).sort().map((k) => [k, canonical(v[k])])) : v;
+export const stable = (v) => JSON.stringify(canonical(v));
+export const digest = (v) => createHash('sha256').update(typeof v === 'string' ? v : stable(v)).digest('hex');
+export const read = (file) => JSON.parse(readFileSync(file, 'utf8'));
+export const write = (file, value) => { mkdirSync(join(file, '..'), { recursive: true }); writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`); };
+export const requireThat = (condition, message) => { if (!condition) throw new Error(message); };
+export const idPattern = /^[a-z][a-z0-9-]*$/;
+export const packagePattern = /^@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/;
+export const versionPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+export function exactKeys(value, keys, label) {
+  requireThat(value && typeof value === 'object' && !Array.isArray(value), `${label}: expected an object`);
+  requireThat(Object.keys(value).every((k) => keys.includes(k)), `${label}: unknown field`);
+}
+export function validateSources(sources) {
+  requireThat(Array.isArray(sources), 'sources must be an array');
+  const names = new Set();
+  for (const s of sources) {
+    exactKeys(s, ['name', 'repository', 'scope', 'official', 'protocol', 'workflow'], 'source');
+    requireThat(idPattern.test(s.name) && !names.has(s.name), 'source name must be unique');
+    requireThat(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(s.repository), 'source repository must be owner/repo');
+    requireThat(/^@[a-z0-9][a-z0-9._-]*$/.test(s.scope), 'source scope must be an npm scope');
+    requireThat(s.protocol === '3' && typeof s.official === 'boolean', 'source must declare Protocol 3 and maintenance identity');
+    requireThat(/^[A-Za-z0-9_-]+\.ya?ml$/.test(s.workflow ?? 'release.yml'), 'source workflow must be a filename');
+    names.add(s.name);
+  }
+  return sources;
+}
+export function validateSubmission(s, sources) {
+  exactKeys(s, ['schemaVersion', 'source', 'vendor', 'package', 'version', 'integrity'], 'submission');
+  requireThat(s.schemaVersion === 1, 'unsupported submission schema');
+  requireThat(typeof s.vendor === 'string' && idPattern.test(s.vendor), 'invalid vendor');
+  requireThat(packagePattern.test(s.package), 'package must have a publisher scope');
+  requireThat(versionPattern.test(s.version), 'version must be exact semver without build metadata');
+  if (s.version.includes('-')) requireThat(s.version.split('-').slice(1).join('-').split('.').every((x) => !/^0\d+$/.test(x)), 'numeric prerelease identifiers cannot have leading zeros');
+  requireThat(/^sha512-[A-Za-z0-9+/]{86}==$/.test(s.integrity), 'integrity must be a single SHA-512 SRI');
+  const source = sources.find((x) => x.name === s.source);
+  requireThat(source && s.package.startsWith(`${source.scope}/`), 'package is outside its registered source scope');
+  return source;
+}
+export const submissionId = (s) => digest(s);
+export function loadIndex(root) {
+  const sources = validateSources(read(join(root, 'sources.json')));
+  const vendors = existsSync(join(root, 'vendors')) ? readdirSync(join(root, 'vendors')).filter((f) => f.endsWith('.json')).sort().map((f) => read(join(root, 'vendors', f))) : [];
+  const recommendations = existsSync(join(root, 'recommendations.json')) ? read(join(root, 'recommendations.json')) : {};
+  const revocations = existsSync(join(root, 'revocations.json')) ? read(join(root, 'revocations.json')) : [];
+  return { sources, vendors, recommendations, revocations };
+}
+export function validateIndex(index) {
+  validateSources(index.sources);
+  const identities = new Map();
+  const packageOwners = new Map();
+  const vendors = new Set();
+  for (const e of index.vendors) {
+    requireThat(idPattern.test(e.vendor) && !vendors.has(e.vendor) && Array.isArray(e.packages), 'invalid or repeated vendor');
+    vendors.add(e.vendor);
+    const packages = new Set();
+    for (const p of e.packages) {
+      const source = index.sources.find((s) => s.name === p.source);
+      requireThat(packagePattern.test(p.name) && source && p.name.startsWith(`${source.scope}/`) && !packages.has(p.name), 'invalid or repeated package/source');
+      packages.add(p.name);
+      const owner = packageOwners.get(p.name);
+      requireThat(!owner || (owner.vendor === e.vendor && owner.source === p.source), 'package vendor and source are immutable across versions');
+      packageOwners.set(p.name, { vendor: e.vendor, source: p.source });
+      const versions = new Set();
+      for (const v of p.versions) {
+        requireThat(versionPattern.test(v.version) && !versions.has(v.version), 'invalid or repeated version');
+        versions.add(v.version);
+        requireThat(['live', 'pending', 'rejected'].includes(v.status), 'invalid version status');
+        const key = `${p.name}@${v.version}`;
+        requireThat(!identities.has(key), `${key}: repeated package identity across vendors`);
+        identities.set(key, { vendor: e.vendor, source: p.source, ...v });
+      }
+    }
+  }
+  requireThat(index.recommendations && typeof index.recommendations === 'object' && !Array.isArray(index.recommendations), 'recommendations must be an object');
+  for (const [vendor, name] of Object.entries(index.recommendations)) requireThat(index.vendors.some((e) => e.vendor === vendor && e.packages.some((p) => p.name === name && p.versions.some((v) => v.status === 'live'))), `${vendor}: recommendation has no live package`);
+  requireThat(Array.isArray(index.revocations), 'revocations must be an array');
+  const revoked = new Set();
+  for (const r of index.revocations) {
+    exactKeys(r, ['package', 'version', 'reason'], 'revocation');
+    const key = `${r.package}@${r.version}`;
+    requireThat(identities.has(key) && !revoked.has(key) && typeof r.reason === 'string' && r.reason.trim(), 'revocation needs an existing unique release and reason');
+    revoked.add(key);
+  }
+  return index;
+}
+export const revoked = (index, name, version) => index.revocations.some((r) => r.package === name && r.version === version);
+export const compareVersions = (a, b) => { const x = a.split('.').map(Number), y = b.split('.').map(Number); return x[0] - y[0] || x[1] - y[1] || x[2] - y[2]; };
+export function selection(index, entry) {
+  const candidates = entry.packages.map((p) => ({ p, v: p.versions.filter((v) => v.status === 'live' && !v.version.includes('-') && !revoked(index, p.name, v.version)).sort((a, b) => compareVersions(b.version, a.version))[0] })).filter((c) => c.v);
+  const recommended = index.recommendations[entry.vendor];
+  const choice = recommended ? candidates.find((c) => c.p.name === recommended) : candidates.length === 1 ? candidates[0] : undefined;
+  return { candidates, recommended, choice };
+}
+export function defaults(index) {
+  validateIndex(index);
+  const out = {};
+  for (const e of index.vendors) {
+    const { candidates, recommended, choice } = selection(index, e);
+    if (!choice && candidates.length) throw new Error(`${e.vendor}: select a live recommended package; competing publishers are not ordered by version`);
+    if (recommended && !choice) throw new Error(`${e.vendor}: recommended package has no selectable release`);
+    if (choice) out[e.vendor] = { name: choice.p.name, version: choice.v.version, source: choice.p.source, ...(choice.v.integrity ? { integrity: choice.v.integrity } : {}) };
+  }
+  return out;
+}
+
+/** A PR contributes one data change. Nothing from its tree is executed. */
+export function classify(files, base, contents) {
+  requireThat(files.length > 0, 'empty change');
+  if (files.length === 1 && /^(submissions|reassessments)\/[a-f0-9]{64}\.json$/.test(files[0].filename)) {
+    const f = files[0];
+    requireThat(f.status === 'added', 'admitted submissions are immutable');
+    const submission = JSON.parse(contents[f.filename]);
+    const source = validateSubmission(submission, base.sources);
+    const reassessment = f.filename.startsWith('reassessments/');
+    requireThat(f.filename === `${reassessment ? 'reassessments' : 'submissions'}/${submissionId(submission)}.json`, 'submission filename does not match its identity');
+    const previous = base.vendors.find((e) => e.vendor === submission.vendor)?.packages.find((p) => p.name === submission.package && p.source === submission.source)?.versions.find((v) => v.version === submission.version);
+    if (reassessment) requireThat(previous?.status === 'live' && !previous.submission && !previous.assessment && (!previous.integrity || previous.integrity === submission.integrity), 'reassessment needs an unassessed historical release with identical identity');
+    else requireThat(!base.vendors.some((e) => e.packages.some((p) => p.name === submission.package && p.versions.some((v) => v.version === submission.version))), 'release already in catalog');
+    return { kind: reassessment ? 'reassessment' : 'submission', submission, source };
+  }
+  requireThat(!files.some((f) => f.filename.startsWith('submissions/') || f.filename.startsWith('reassessments/') || f.filename.startsWith('vendors/')), 'submissions cannot be mixed with policy, executable, or index edits');
+  if (files.length === 1 && files[0].filename === 'sources.json') {
+    const sources = validateSources(JSON.parse(contents['sources.json']));
+    requireThat(sources.length === base.sources.length + 1 && base.sources.every((s) => sources.some((x) => stable(x) === stable(s))), 'source registration adds one source; existing registrations are immutable');
+    return { kind: 'registration', source: sources.find((s) => !base.sources.some((x) => x.name === s.name)) };
+  }
+  requireThat(!files.some((f) => f.filename === 'sources.json'), 'source registration must be a separate data-only PR');
+  if (files.every((f) => ['recommendations.json', 'revocations.json'].includes(f.filename))) {
+    const next = { ...base };
+    for (const f of files) { requireThat(f.status !== 'removed', 'policy data cannot be removed'); next[f.filename.split('.')[0]] = JSON.parse(contents[f.filename]); }
+    validateIndex(next);
+    requireThat(base.revocations.every((r) => next.revocations.some((x) => stable(x) === stable(r))), 'revocations are append-only');
+    defaults(next);
+    return { kind: 'selection' };
+  }
+  requireThat(!files.some((f) => ['recommendations.json', 'revocations.json'].includes(f.filename)), 'selection changes must be a separate data-only PR');
+  return { kind: 'maintenance' };
+}
+
+export function admit(index, submission, commit, at, reassessment = false) {
+  validateSubmission(submission, index.sources);
+  requireThat(/^[a-f0-9]{40}$/.test(commit) && Number.isFinite(Date.parse(at)), 'admission needs a merge commit and timestamp');
+  const existing = index.vendors.flatMap((e) => e.packages.flatMap((p) => p.name === submission.package ? p.versions.map((v) => ({ e, p, v })) : [])).find(({ v }) => v.version === submission.version);
+  if (existing) {
+    if (reassessment) {
+      requireThat(existing.e.vendor === submission.vendor && existing.p.source === submission.source && existing.v.status === 'live' && (!existing.v.integrity || existing.v.integrity === submission.integrity) && !existing.v.submission && (!existing.v.assessment || existing.v.assessment === submissionId(submission)), 'historical reassessment identity conflict');
+      Object.assign(existing.v, { integrity: submission.integrity, assessment: submissionId(submission), assessmentCommit: commit, assessedAt: at });
+      return validateIndex(index);
+    }
+    requireThat(existing.e.vendor === submission.vendor && existing.p.source === submission.source && existing.v.integrity === submission.integrity && existing.v.submission === submissionId(submission), 'immutable release identity conflict');
+    return index;
+  }
+  let e = index.vendors.find((v) => v.vendor === submission.vendor);
+  if (!e) { e = { vendor: submission.vendor, packages: [] }; index.vendors.push(e); }
+  let p = e.packages.find((p) => p.name === submission.package);
+  if (!p) { p = { name: submission.package, source: submission.source, versions: [] }; e.packages.push(p); }
+  requireThat(p.source === submission.source, 'package source is immutable');
+  p.versions.push({ version: submission.version, status: 'live', integrity: submission.integrity, submission: submissionId(submission), commit, at, by: 'moderated-merge' });
+  return validateIndex(index);
+}
+
+export function compareReports(current, previous) {
+  if (!previous) return { baseline: null, note: 'No independently measured baseline; regressions are not assessed.' };
+  requireThat(current.package === previous.package, 'cannot compare different publishers');
+  const old = new Set(previous.quick?.servedOperations ?? []), now = new Set(current.quick?.servedOperations ?? []);
+  return { baseline: previous.version, added: [...now].filter((x) => !old.has(x)), removed: [...old].filter((x) => !now.has(x)), previousDenominator: previous.quick?.surface?.total ?? null, denominator: current.quick?.surface?.total ?? null, previousFailures: previous.quick?.failures?.length ?? null, failures: current.quick?.failures?.length ?? null };
+}

package/lib/propose.mjs

@@ -0,0 +1,29 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { read, requireThat, stable, submissionId, validateSubmission } from './model.mjs';
+
+/** Publisher-side automation opens a data PR; it never approves, merges or edits the index. */
+export async function propose(github, directory, reassess = false) {
+  const base = await github.call('git/ref/heads/main');
+  const sources = JSON.parse(await github.content('sources.json', base.object.sha));
+  const results = [];
+  for (const filename of readdirSync(directory).filter((f) => /^[a-f0-9]{64}\.json$/.test(f)).sort()) {
+    const submission = read(join(directory, filename));
+    validateSubmission(submission, sources);
+    const id = submissionId(submission), kind = reassess ? 'reassessment' : 'submission', path = `${reassess ? 'reassessments' : 'submissions'}/${id}.json`, branch = `${kind}/${id}`;
+    requireThat(filename === `${id}.json`, 'submission filename mismatch');
+    const existing = await github.call(`pulls?state=all&head=${encodeURIComponent(`${github.repository.split('/')[0]}:${branch}`)}&base=main`);
+    if (existing.length) { results.push({ id, url: existing[0].html_url, state: existing[0].state }); continue; }
+    let ref;
+    try { ref = await github.call(`git/ref/heads/${branch}`); }
+    catch (e) { if (!e.message.endsWith('HTTP 404')) throw e; ref = await github.call('git/refs', 'POST', { ref: `refs/heads/${branch}`, sha: base.object.sha }); }
+    let held;
+    try { held = JSON.parse(await github.content(path, ref.object.sha)); }
+    catch (e) { if (!e.message.endsWith('HTTP 404')) throw e; }
+    if (held) requireThat(stable(held) === stable(submission), 'existing submission branch has different data');
+    else await github.call(`contents/${path}`, 'PUT', { message: `Submit ${submission.package}@${submission.version}`, branch, content: Buffer.from(`${JSON.stringify(submission, null, 2)}\n`).toString('base64') });
+    const pr = await github.call('pulls', 'POST', { title: `Submit ${submission.package}@${submission.version}`, head: branch, base: 'main', body: `Published artifact submission for ${submission.vendor}.\n\nThe catalog prepares evidence; moderators decide admission.\n\nIntegrity: \`${submission.integrity}\`` });
+    results.push({ id, url: pr.html_url, state: pr.state });
+  }
+  return results;
+}