@verndale/accessibility-standards 1.0.0 → 2.0.0

package/lib/render.mjs

@@ -1,14 +1,20 @@
 import { compileApplicability, resolutionStates, triggerStates } from './compile-applicability.mjs';
+import { buildLaneCoverage } from './coverage.mjs';
 import { digest } from './digest.mjs';
+import { projectionProvenance } from './provenance.mjs';
 
 export const marker = 'GENERATED by @verndale/accessibility-standards; DO NOT EDIT';
 
-function json(payload) {
-  return `${JSON.stringify({ _generated: marker, ...payload }, null, 2)}\n`;
+function json(payload, provenance) {
+  return `${JSON.stringify({ _generated: marker, _provenance: provenance, ...payload }, null, 2)}\n`;
 }
 
-function markdown(title, records, body) {
-  return `<!-- ${marker} -->\n# ${title}\n\n${records.map(body).join('\n\n')}\n`;
+function markdownDocument(title, content, provenance) {
+  return `<!-- ${marker} -->\n<!-- package: ${provenance.package}; profile: ${provenance.profile}@${provenance.profile_version}; schema: ${provenance.schema_version}; source-digest: ${provenance.source_digest}; profile-digest: ${provenance.profile_digest} -->\n# ${title}\n\n${content}\n`;
+}
+
+function markdown(title, records, body, provenance) {
+  return markdownDocument(title, records.map(body).join('\n\n'), provenance);
 }
 
 function semanticSection(item) {
@@ -16,39 +22,81 @@ function semanticSection(item) {
 }
 
 function patternSection(item) {
-  return `## ${item.id}\n\nRequires: ${item.requires.join(', ')}.\n\nBehavior:\n${item.behavior.map((line) => `- ${line}`).join('\n')}\n\nEvidence: ${item.evidence_routes.join(', ')}.`;
+  return `## ${item.id}\n\nRequires: ${item.requires.join(', ')}.\n\nScope: ${item.scope}.\n\nBehavior:\n${item.behavior.map((line) => `- ${line}`).join('\n')}\n\nProduct decisions: ${item.product_decisions.join(', ')}.\n\nFunctional Spec bindings: ${item.functional_spec_bindings.join(', ')}.\n\nImplementation outcomes: ${item.implementation_outcomes.join(', ')}.\n\nEvidence: ${item.evidence_routes.join(', ')}.`;
+}
+
+function requirementSection(item) {
+  return `## ${item.id}\n\n${item.requirement}`;
+}
+
+function applicabilitySection(item) {
+  return `## ${item.id}\n\nWhen: \`${JSON.stringify(item.when)}\`\n\nOutcomes: ${item.outcomes.join(', ')}.\n\nEvidence: ${item.evidence.join(', ')}.`;
+}
+
+function evidenceSection(data) {
+  return `## Evidence routing\n\n${data.evidence.rule}\n\n${Object.entries(data.evidence.proof_kinds).map(([id, route]) => `- ${id}: ${route.purpose}; capability: ${route.required_capability}`).join('\n')}`;
 }
 
 export function buildArtifacts(data, profile) {
+  const provenance = projectionProvenance(data, profile);
+  const foundations = [...data.foundations].sort(byId);
   const semantics = [...data.semantics].sort(byId);
   const patterns = [...data.patterns].sort(byId);
+  const policies = [...data.policies].sort(byId);
   const compiled = compileApplicability(data.matrix, data.facts);
-  const ids = [...semantics.map(({ id }) => id), ...patterns.map(({ id }) => id), ...data.matrix.rows.map(({ id }) => id)].sort();
-  const laneCoverage = Object.fromEntries(Object.keys(data.evidence.proof_kinds).sort().map((lane) => [lane, idsForLane(data, lane)]));
+  const bindingDigest = digest(data.uiDesignBrainBindings);
+  const uiPatternIds = data.uiDesignBrainBindings.bindings.map(({ ui_pattern_id }) => ui_pattern_id);
+  const ids = [...foundations, ...semantics, ...patterns, ...policies, ...data.matrix.rows].map(({ id }) => id).sort();
+  const laneCoverage = buildLaneCoverage(data);
   const artifacts = new Map();
-  artifacts.set('semanticsJson', json({ schema_version: 1, semantics }));
-  artifacts.set('patternContracts', json({ schema_version: 1, patterns }));
-  artifacts.set('coverageManifest', json({ schema_version: 1, projected_ids: ids, lane_coverage: laneCoverage }));
+  artifacts.set('semanticsJson', json({ schema_version: data.contract.schema_version, foundations, semantics, policies }, provenance));
+  artifacts.set('patternContracts', json({ schema_version: data.contract.schema_version, patterns }, provenance));
+  artifacts.set('uiDesignBrainBindings', json({ schema_version: data.contract.schema_version, binding_schema_version: data.uiDesignBrainBindings.version, source: data.uiDesignBrainBindings.source, binding_digest: bindingDigest, bindings: data.uiDesignBrainBindings.bindings }, provenance));
+  artifacts.set('coverageManifest', json({
+    schema_version: data.contract.schema_version,
+    projected_ids: ids,
+    ui_pattern_ids: uiPatternIds,
+    ui_design_brain: { ...data.uiDesignBrainBindings.source, binding_digest: bindingDigest },
+    lane_coverage: laneCoverage
+  }, provenance));
   if (profile === 'conductor') {
-    artifacts.set('semanticsMarkdown', markdown('Accessibility semantics', semantics, semanticSection));
-    artifacts.set('qualityMarkdown', markdown('Accessibility quality contract', patterns, patternSection));
-    artifacts.set('applicabilityMatrix', json({ schema_version: 1, trigger_states: triggerStates, resolution_states: resolutionStates, facts: data.facts.facts, rows: compiled }));
-    for (const pattern of patterns) artifacts.set(`pattern:${pattern.id}`, json({ schema_version: 1, pattern }));
+    const authoritySections = [
+      ...foundations.map(requirementSection),
+      ...semantics.map(semanticSection),
+      ...policies.map(requirementSection),
+    ].join('\n\n');
+    const qualitySections = [
+      ...patterns.map(patternSection),
+      ...compiled.map(applicabilitySection),
+      evidenceSection(data),
+    ].join('\n\n');
+    artifacts.set('semanticsMarkdown', markdownDocument('Accessibility foundations, semantics, and policies', authoritySections, provenance));
+    artifacts.set('qualityMarkdown', markdownDocument('Accessibility quality contract', qualitySections, provenance));
+    artifacts.set('applicabilityMatrix', json({ schema_version: data.contract.schema_version, trigger_states: triggerStates, resolution_states: resolutionStates, facts: data.facts.facts, rows: compiled, evidence: data.evidence }, provenance));
+    for (const pattern of patterns) artifacts.set(`pattern:${pattern.id}`, json({ schema_version: data.contract.schema_version, pattern }, provenance));
   } else if (profile === 'ai-orchestration') {
-    for (const semantic of semantics) artifacts.set(`semantic:${semantic.id}`, markdown(semantic.id, [semantic], semanticSection));
-    for (const pattern of patterns) artifacts.set(`pattern:${pattern.id}`, markdown(pattern.id, [pattern], patternSection));
-    artifacts.set('implementation', markdown('Accessibility implementation contract', [...semantics, ...patterns], (item) => item.kind === 'semantic' ? semanticSection(item) : patternSection(item)));
-    artifacts.set('testing', `<!-- ${marker} -->\n# Accessibility testing contract\n\n${Object.entries(laneCoverage).map(([lane, laneIds]) => `## ${lane}\n\n${laneIds.map((id) => `- ${id}`).join('\n')}`).join('\n\n')}\n`);
-    artifacts.set('review', `<!-- ${marker} -->\n# Accessibility review contract\n\nReview in this order: source compatibility, semantic dependencies, pattern behavior, implementation outcomes, test lanes, human evidence.\n\n${ids.map((id) => `- ${id}`).join('\n')}\n`);
+    for (const semantic of semantics) artifacts.set(`semantic:${semantic.id}`, markdown(semantic.id, [semantic], semanticSection, provenance));
+    for (const pattern of patterns) artifacts.set(`pattern:${pattern.id}`, markdown(pattern.id, [pattern], patternSection, provenance));
+    const implementationSections = [
+      ...foundations.map(requirementSection),
+      ...semantics.map(semanticSection),
+      ...patterns.map(patternSection),
+      ...compiled.map(applicabilitySection),
+      ...policies.map(requirementSection),
+      evidenceSection(data),
+    ].join('\n\n');
+    artifacts.set('implementation', markdownDocument('Accessibility implementation contract', implementationSections, provenance));
+    artifacts.set('testing', markdownDocument('Accessibility testing contract', Object.entries(laneCoverage).map(([lane, laneIds]) => `## ${lane}\n\n${laneIds.map((id) => `- ${id}`).join('\n')}`).join('\n\n'), provenance));
+    artifacts.set('review', markdownDocument('Accessibility review contract', `Review in this order: source compatibility, foundations, semantic dependencies, pattern behavior, applicability outcomes, implementation outcomes, test lanes, human evidence.\n\n${ids.map((id) => `- ${id}`).join('\n')}`, provenance));
   } else throw new Error(`Unknown profile: ${profile}`);
   return artifacts;
 }
 
 export function defaultPath(key, profile) {
   const fixed = profile === 'conductor' ? {
-    semanticsMarkdown: 'a11y-semantics.md', qualityMarkdown: 'accessibility-quality.md', semanticsJson: 'semantics.json', patternContracts: 'pattern-contracts.json', applicabilityMatrix: 'applicability-matrix.json', coverageManifest: 'coverage-manifest.json'
+    semanticsMarkdown: 'a11y-semantics.md', qualityMarkdown: 'accessibility-quality.md', semanticsJson: 'semantics.json', patternContracts: 'pattern-contracts.json', applicabilityMatrix: 'applicability-matrix.json', uiDesignBrainBindings: 'ui-design-brain-bindings.json', coverageManifest: 'coverage-manifest.json'
   } : {
-    semanticsJson: 'semantics.json', patternContracts: 'pattern-contracts.json', coverageManifest: 'coverage-manifest.json', implementation: 'implementation/accessibility.md', testing: 'testing/accessibility.md', review: 'review/accessibility.md'
+    semanticsJson: 'semantics.json', patternContracts: 'pattern-contracts.json', uiDesignBrainBindings: 'ui-design-brain-bindings.json', coverageManifest: 'coverage-manifest.json', implementation: 'implementation/accessibility.md', testing: 'testing/accessibility.md', review: 'review/accessibility.md'
   };
   if (fixed[key]) return fixed[key];
   if (key.startsWith('pattern:')) return `patterns/${key.slice(8).replace('pattern.', '')}.${profile === 'conductor' ? 'json' : 'md'}`;
@@ -60,12 +108,4 @@ export function artifactDigestMap(artifacts) {
   return Object.fromEntries([...artifacts].sort(([a], [b]) => a.localeCompare(b)).map(([key, value]) => [key, digest(value)]));
 }
 
-function idsForLane(data, lane) {
-  return [...new Set([
-    ...data.semantics.filter((item) => item.proof.includes(lane)).map(({ id }) => id),
-    ...data.patterns.filter((item) => item.evidence_routes.includes(lane)).map(({ id }) => id),
-    ...data.matrix.rows.filter((item) => item.evidence.includes(lane)).flatMap((item) => item.outcomes)
-  ])].sort();
-}
-
 const byId = (a, b) => a.id.localeCompare(b.id);

package/lib/sync.mjs

@@ -1,6 +1,5 @@
-import { access, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
-import { tmpdir } from 'node:os';
+import { access, lstat, mkdir, mkdtemp, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { buildProjectionManifest } from './build-manifest.mjs';
 import { digest } from './digest.mjs';
 import { loadStandards, packageRoot } from './load.mjs';
@@ -8,52 +7,112 @@ import { buildArtifacts, defaultPath, marker } from './render.mjs';
 import { validateStandards } from './validate.mjs';
 
 const exists = async (path) => access(path).then(() => true, () => false);
+const configKeys = new Set(['package', 'profile', 'routes', 'outputRoot']);
+const routeKeys = new Set(['version', 'outputs']);
 
-export async function projection({ configPath, check = false, ifNeeded = false }) {
+export async function projection({
+  configPath,
+  check = false,
+  ifNeeded = false,
+  promotionHooks,
+}) {
   const absoluteConfig = resolve(configPath);
   const consumerRoot = dirname(absoluteConfig);
   const config = JSON.parse(await readFile(absoluteConfig, 'utf8'));
-  const expectedPackage = '@verndale/accessibility-standards@1.0.0';
-  if (config.package !== expectedPackage) throw new Error(`Exact package pin required: ${expectedPackage}`);
-  const routesPath = resolve(consumerRoot, config.routes);
+  validateConfig(config);
+  const routesPath = resolveInside(consumerRoot, config.routes, 'routes');
+  await assertNoSymlinkPath(consumerRoot, routesPath, 'routes');
   const routes = JSON.parse(await readFile(routesPath, 'utf8'));
+  validateRoutes(routes);
   const data = await loadStandards(packageRoot);
   validateStandards(data);
-  const outputRoot = resolve(consumerRoot, config.outputRoot ?? '.');
+  const expectedPackage = `@verndale/accessibility-standards@${data.contract.package_version}`;
+  if (config.package !== expectedPackage) throw new Error(`Exact installed package pin required: ${expectedPackage}`);
+  const outputRoot = resolveInside(consumerRoot, config.outputRoot ?? '.', 'outputRoot', {
+    allowRoot: true,
+  });
+  await assertNoSymlinkPath(consumerRoot, outputRoot, 'outputRoot');
   const artifacts = buildArtifacts(data, config.profile);
   const sourceKey = 'source';
-  const sourcePath = resolveOutput(outputRoot, routes.outputs[sourceKey] ?? 'accessibility.source.json');
-  const manifest = buildProjectionManifest({ data, profile: config.profile, config, routes, artifacts });
+  const artifactKeys = [...artifacts.keys(), sourceKey];
+  validateRouteKeys(routes, artifactKeys);
+  const paths = new Map(
+    artifactKeys.map((key) => [
+      key,
+      resolveOutput(outputRoot, routeFor(key, routes, config.profile)),
+    ]),
+  );
+  assertUniqueTargets(paths);
+  for (const [key, path] of paths) {
+    await assertNoSymlinkPath(outputRoot, path, `output ${key}`);
+  }
+  const sourcePath = paths.get(sourceKey);
+  const manifest = buildProjectionManifest({
+    data,
+    profile: config.profile,
+    config,
+    routes,
+    artifacts,
+  });
+  manifest.output_paths = Object.fromEntries(
+    [...paths]
+      .map(([key, path]) => [key, relative(outputRoot, path).split(sep).join('/')])
+      .sort(([left], [right]) => left.localeCompare(right)),
+  );
+  manifest.manifest_digest = digest(manifest);
   artifacts.set(sourceKey, `${JSON.stringify(manifest, null, 2)}\n`);
-  const paths = new Map([...artifacts].map(([key]) => [key, resolveOutput(outputRoot, routeFor(key, routes, config.profile))]));
   if (check) return checkProjection(artifacts, paths);
   if (ifNeeded && await projectionMatches(artifacts, paths)) return { changed: false, files: paths.size };
-  await protectManagedFiles(paths, sourcePath);
-  const stage = join(tmpdir(), `a11y-sync-${process.pid}-${Date.now()}`);
-  await mkdir(stage, { recursive: true });
+  const removals = await protectManagedFiles(paths, sourcePath, outputRoot);
+  const stage = await mkdtemp(join(consumerRoot, '.accessibility-sync-'));
   try {
     let index = 0;
-    const staged = [];
+    const writes = [];
     for (const [key, content] of artifacts) {
-      const temp = join(stage, String(index++));
+      const temp = join(stage, 'candidate', String(index++));
+      await mkdir(dirname(temp), { recursive: true });
       await writeFile(temp, content);
-      staged.push([temp, paths.get(key)]);
-    }
-    for (const [temp, target] of staged) {
-      await mkdir(dirname(target), { recursive: true });
-      await rename(temp, target);
+      const staged = await readFile(temp, 'utf8');
+      if (staged !== content || !staged.includes(marker)) {
+        throw new Error(`Staged projection validation failed for ${key}`);
+      }
+      writes.push({ key, temp, target: paths.get(key) });
     }
-  } finally { await rm(stage, { recursive: true, force: true }); }
-  await checkProjection(artifacts, paths);
+    await promoteProjectionTransaction({
+      writes,
+      removals,
+      stage,
+      validate: () => checkProjection(artifacts, paths),
+      hooks: promotionHooks,
+    });
+  } finally {
+    await rm(stage, { recursive: true, force: true });
+  }
   return { changed: true, files: paths.size };
 }
 
-async function protectManagedFiles(paths, sourcePath) {
+async function protectManagedFiles(paths, sourcePath, outputRoot) {
   let prior = null;
   if (await exists(sourcePath)) {
     const raw = await readFile(sourcePath, 'utf8');
     if (!raw.includes(marker)) throw new Error(`Refusing to overwrite unmarked provenance: ${sourcePath}`);
-    prior = JSON.parse(raw);
+    try {
+      prior = JSON.parse(raw);
+    } catch {
+      throw new Error(`Refusing to overwrite invalid generated provenance: ${sourcePath}`);
+    }
+    const { manifest_digest: manifestDigest, ...unsignedManifest } = prior;
+    if (!/^[a-f0-9]{64}$/.test(manifestDigest ?? '') || digest(unsignedManifest) !== manifestDigest) {
+      throw new Error(`Refusing to overwrite locally modified generated provenance: ${sourcePath}`);
+    }
+  } else {
+    const existing = [];
+    for (const path of paths.values()) if (await exists(path)) existing.push(path);
+    if (existing.length > 0) {
+      throw new Error(
+        `Refusing to overwrite generated targets without their provenance: ${existing.join(', ')}`,
+      );
+    }
   }
   for (const [key, path] of paths) {
     if (!await exists(path)) continue;
@@ -62,6 +121,82 @@ async function protectManagedFiles(paths, sourcePath) {
     const expected = prior?.output_digests?.[key];
     if (expected && digest(raw) !== expected) throw new Error(`Refusing to overwrite locally modified generated target: ${path}`);
   }
+  const removals = [];
+  for (const [key, priorRelativePath] of Object.entries(prior?.output_paths ?? {})) {
+    const priorPath = resolveOutput(outputRoot, priorRelativePath);
+    if ([...paths.values()].includes(priorPath) || !await exists(priorPath)) continue;
+    const raw = await readFile(priorPath, 'utf8');
+    if (!raw.includes(marker)) {
+      throw new Error(`Refusing to remove unmarked prior generated target: ${priorPath}`);
+    }
+    const expected = prior?.output_digests?.[key];
+    if (expected && digest(raw) !== expected) {
+      throw new Error(`Refusing to remove locally modified prior generated target: ${priorPath}`);
+    }
+    removals.push({ key, target: priorPath });
+  }
+  return removals;
+}
+
+export async function promoteProjectionTransaction({
+  writes,
+  removals = [],
+  stage,
+  validate,
+  hooks = {},
+}) {
+  const records = [];
+  const operations = [
+    ...writes.map((write) => ({ ...write, kind: 'write' })),
+    ...removals.map((removal) => ({ ...removal, kind: 'remove', temp: null })),
+  ];
+  const backupRoot = join(stage, 'backup');
+  await mkdir(backupRoot, { recursive: true });
+  try {
+    for (let index = 0; index < operations.length; index += 1) {
+      const operation = operations[index];
+      await hooks.beforePromote?.({ index, key: operation.key, target: operation.target });
+      await mkdir(dirname(operation.target), { recursive: true });
+      const record = {
+        ...operation,
+        backup: join(backupRoot, String(index)),
+        backedUp: false,
+        placed: false,
+      };
+      records.push(record);
+      if (await exists(operation.target)) {
+        await rename(operation.target, record.backup);
+        record.backedUp = true;
+      }
+      if (operation.kind === 'write') {
+        await rename(operation.temp, operation.target);
+        record.placed = true;
+      }
+    }
+    await validate();
+  } catch (error) {
+    const rollbackErrors = [];
+    for (const record of [...records].reverse()) {
+      try {
+        if (record.placed && await exists(record.target)) {
+          await rm(record.target, { force: true });
+        }
+        if (record.backedUp && await exists(record.backup)) {
+          await mkdir(dirname(record.target), { recursive: true });
+          await rename(record.backup, record.target);
+        }
+      } catch (rollbackError) {
+        rollbackErrors.push(`${record.target}: ${rollbackError.message}`);
+      }
+    }
+    if (rollbackErrors.length > 0) {
+      throw new Error(
+        `${error.message}; projection rollback failed: ${rollbackErrors.join('; ')}`,
+        { cause: error },
+      );
+    }
+    throw error;
+  }
 }
 
 async function projectionMatches(artifacts, paths) {
@@ -89,6 +224,85 @@ function routeFor(key, routes, profile) {
 }
 
 function resolveOutput(root, path) {
-  const target = isAbsolute(path) ? path : resolve(root, path);
+  return resolveInside(root, path, 'output');
+}
+
+function validateConfig(config) {
+  if (!isPlainObject(config)) throw new Error('Consumer config must be an object');
+  rejectUnknownKeys(config, configKeys, 'consumer config');
+  if (typeof config.package !== 'string' || !config.package) {
+    throw new Error('Consumer config package is required');
+  }
+  if (!['conductor', 'ai-orchestration'].includes(config.profile)) {
+    throw new Error(`Unsupported accessibility profile: ${config.profile}`);
+  }
+  for (const key of ['routes', ...(config.outputRoot === undefined ? [] : ['outputRoot'])]) {
+    if (typeof config[key] !== 'string' || !config[key].trim()) {
+      throw new Error(`Consumer config ${key} must be a non-empty relative path`);
+    }
+  }
+}
+
+function validateRoutes(routes) {
+  if (!isPlainObject(routes)) throw new Error('Consumer routes must be an object');
+  rejectUnknownKeys(routes, routeKeys, 'consumer routes');
+  if (routes.version !== 1) throw new Error('Consumer routes version must be 1');
+  if (!isPlainObject(routes.outputs)) throw new Error('Consumer routes outputs must be an object');
+  for (const [key, value] of Object.entries(routes.outputs)) {
+    if (typeof value !== 'string' || !value.trim()) {
+      throw new Error(`Consumer route ${key} must be a non-empty relative path`);
+    }
+  }
+}
+
+function validateRouteKeys(routes, artifactKeys) {
+  const allowed = new Set([...artifactKeys, 'patterns', 'semantics']);
+  const unknown = Object.keys(routes.outputs).filter((key) => !allowed.has(key));
+  if (unknown.length > 0) throw new Error(`Unsupported consumer route keys: ${unknown.join(', ')}`);
+}
+
+function assertUniqueTargets(paths) {
+  const owners = new Map();
+  for (const [key, path] of paths) {
+    const prior = owners.get(path);
+    if (prior) throw new Error(`Consumer routes collide at ${path}: ${prior}, ${key}`);
+    owners.set(path, key);
+  }
+}
+
+function resolveInside(root, candidate, label, { allowRoot = false } = {}) {
+  if (typeof candidate !== 'string' || !candidate.trim() || isAbsolute(candidate)) {
+    throw new Error(`${label} must be a non-empty relative path`);
+  }
+  const target = resolve(root, candidate);
+  const rel = relative(root, target);
+  if ((!allowRoot && rel === '') || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    throw new Error(`${label} escapes its allowed root: ${candidate}`);
+  }
   return target;
 }
+
+async function assertNoSymlinkPath(root, target, label) {
+  const rel = relative(root, target);
+  if (rel === '') return;
+  let cursor = root;
+  for (const part of rel.split(sep)) {
+    cursor = join(cursor, part);
+    try {
+      const stats = await lstat(cursor);
+      if (stats.isSymbolicLink()) throw new Error(`${label} traverses a symbolic link: ${cursor}`);
+    } catch (error) {
+      if (error?.code === 'ENOENT') return;
+      throw error;
+    }
+  }
+}
+
+function rejectUnknownKeys(value, allowed, label) {
+  const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+  if (unknown.length > 0) throw new Error(`${label} has unknown keys: ${unknown.join(', ')}`);
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}