@open-agent-toolkit/cli 0.2.72 → 0.2.74

package/assets/skills/explainer-kit/scripts/lib/contracts.mjs

@@ -1,41 +1,12 @@
 import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 
-import {
-  composePublicationTarget,
-  normalizePublishRoots,
-} from './s3-roots.mjs';
 import { validatePortablePath } from './safe-paths.mjs';
-import {
-  parseCanonicalGithubBlobUrl,
-  validateCanonicalGithubBlobTuple,
-} from './source-backlinks.mjs';
 
 const SCHEMA_FILES = {
-  'run-request': 'run-request.schema.json',
   'fact-base': 'fact-base.schema.json',
-  theme: 'theme.schema.json',
   manifest: 'manifest.schema.json',
-  'build-record': 'build-record.schema.json',
-  'durability-evidence': 'durability-evidence.schema.json',
-  'publish-request/v1': 'publish-request.v1.schema.json',
-  'publish-request/v2': 'publish-request.v2.schema.json',
-  'publish-receipt/v1': 'publish-receipt.v1.schema.json',
-  'publish-receipt/v2': 'publish-receipt.v2.schema.json',
-  'author-request/v2': 'author-request.v2.schema.json',
-  'author-request/v3': 'author-request.v3.schema.json',
-  'author-result/v2': 'author-result.v2.schema.json',
-  'set-plan': 'set-plan.v1.schema.json',
-  'visual-review-request': 'visual-review-request.v1.schema.json',
-  'visual-review-result': 'visual-review-result.v1.schema.json',
-  'visual-review-evidence': 'visual-review-evidence.v1.schema.json',
-  'terminal-evidence': 'terminal-evidence.v1.schema.json',
-};
-const DEFAULT_SCHEMA_KEYS = {
-  'author-request': 'author-request/v3',
-  'author-result': 'author-result/v2',
-  'publish-request': 'publish-request/v2',
-  'publish-receipt': 'publish-receipt/v2',
+  theme: 'theme.schema.json',
 };
 
 const SCHEMAS = Object.fromEntries(
@@ -49,34 +20,8 @@ const SCHEMAS = Object.fromEntries(
 const SCHEMAS_BY_ID = new Map(
   Object.values(SCHEMAS).map((schema) => [schema.$id, schema]),
 );
-// `validateContract` accepts a schema `$id` as its `kind`, but every downstream
-// gate matches on the short registry form. `'explainer-kit.publish-request/v1'`
-// does not start with `'publish-request'`, so an `$id`-form call skipped the
-// default-deny publication-root gate entirely and answered `valid: true` for a
-// credential-bearing root. Normalize once, here, so no individual gate has to
-// remember to handle both spellings.
-const KIND_BY_SCHEMA_ID = new Map(
-  Object.entries(SCHEMAS).map(([kind, schema]) => [schema.$id, kind]),
-);
-
-function canonicalContractKind(kind) {
-  return KIND_BY_SCHEMA_ID.get(kind) ?? kind;
-}
-
-const LEGACY_PUBLISH_RECEIPT = 'explainer-kit.publish-receipt/v1';
-
-/**
- * True for every publish-receipt shape except the retained v1 replay form.
- *
- * Stated as "not v1" rather than "=== v2" on purpose: keying verification to an
- * exact version string means a future `publish-receipt/v3` silently skips
- * sentinel verification and per-artifact validation, which is the same
- * fail-open shape the publication-root gate was rewritten to eliminate. v1 is
- * the only version that legitimately lacks these facts.
- */
-export function isVerifiablePublishReceipt(value) {
-  return value?.schemaVersion !== LEGACY_PUBLISH_RECEIPT;
-}
+const DATE_TIME_PATTERN =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
 const RAW_SECRET_KEYS = new Set([
   'accesskey',
   'accesskeyid',
@@ -91,104 +36,24 @@ const RAW_SECRET_KEYS = new Set([
   'sessiontoken',
   'token',
 ]);
-const DATE_TIME_PATTERN =
-  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
-const SET_PLAN_RECORD_PATHS = [
-  'source/set-plan/request.json',
-  'source/set-plan/result.json',
-  'source/set-plan/ledger.json',
-  'source/set-plan/portfolio.json',
-  'source/set-plan/drafts.json',
-];
 
-export function validateContract(kind, value, context = {}) {
-  const schema = resolveContractSchema(kind, value);
+export function validateContract(kind, value) {
+  const schema = SCHEMAS[kind] ?? SCHEMAS_BY_ID.get(kind);
   if (!schema) {
-    return {
-      valid: false,
-      errors: [
-        {
-          path: '$',
-          code: 'unknown-kind',
-          message: `Unknown contract kind: ${kind}`,
-        },
-      ],
-    };
+    throw new Error(`Unknown contract kind: ${kind}`);
   }
 
   const errors = [];
-  // Every gate below matches on the short registry form, so an `$id`-form kind
-  // is normalized before dispatch rather than in each gate.
-  const canonicalKind = canonicalContractKind(kind);
   findRawSecrets(value, '$', errors);
   validateSchema(schema, value, '$', schema, errors);
-  validateContractPaths(canonicalKind, value, errors);
-  validatePublicationRoots(canonicalKind, value, errors);
-  validateCrossRecord(canonicalKind, value, context, errors);
-  validateSourceBacklinks(canonicalKind, value, errors);
-  return { valid: errors.length === 0, errors };
-}
-
-function validateSourceBacklinks(kind, value, errors) {
-  if (kind === 'fact-base' || kind === 'explainer-kit.fact-base/v1') {
-    const tuples = [
-      ...(value.sources ?? []),
-      ...(value.claims ?? []).flatMap((claim) => claim.citations ?? []),
-      ...(value.unresolvedClaims ?? []).flatMap(
-        (claim) => claim.citations ?? [],
-      ),
-    ];
-    tuples.forEach((tuple, index) => {
-      const declaresBacklink = ['repository', 'path', 'lineRange', 'url'].some(
-        (field) => tuple[field] !== undefined,
-      );
-      if (declaresBacklink && !validateCanonicalGithubBlobTuple(tuple)) {
-        add(
-          errors,
-          `$.sourceBacklinks[${index}]`,
-          'source-backlink',
-          'Must declare one complete canonical GitHub blob backlink tuple.',
-        );
-      }
-    });
-    return;
-  }
-  if (kind !== 'manifest' && kind !== 'explainer-kit.manifest/v1') return;
-  (value.source?.backlinks ?? []).forEach((entry, index) => {
-    try {
-      parseCanonicalGithubBlobUrl(entry.url);
-    } catch (error) {
-      add(
-        errors,
-        `$.source.backlinks[${index}].url`,
-        'source-backlink',
-        error instanceof Error
-          ? error.message
-          : 'Must be a canonical GitHub blob backlink.',
-      );
-    }
-  });
-}
-
-function resolveContractSchema(kind, value) {
-  if (SCHEMAS[kind]) {
-    return SCHEMAS[kind];
+  validateContractPaths(kind, value, errors);
+  if (schema === SCHEMAS['fact-base']) {
+    rejectRetiredCitationKeys(value, errors);
   }
-  if (SCHEMAS_BY_ID.has(kind)) {
-    return SCHEMAS_BY_ID.get(kind);
-  }
-
-  const defaultKey = DEFAULT_SCHEMA_KEYS[kind];
-  if (!defaultKey) {
-    return null;
+  if (schema === SCHEMAS.manifest) {
+    validateManifest(value, errors);
   }
-
-  const declared = isObject(value)
-    ? SCHEMAS_BY_ID.get(value.schemaVersion)
-    : undefined;
-  return declared?.$id.startsWith(`explainer-kit.${kind}/`)
-    ? declared
-    : SCHEMAS[defaultKey];
+  return { valid: errors.length === 0, errors };
 }
 
 export function canonicalHash(value) {
@@ -202,9 +67,7 @@ export function canonicalStringify(value) {
 }
 
 function canonicalize(value) {
-  if (Array.isArray(value)) {
-    return value.map(canonicalize);
-  }
+  if (Array.isArray(value)) return value.map(canonicalize);
   if (isObject(value)) {
     return Object.fromEntries(
       Object.keys(value)
@@ -215,6 +78,88 @@ function canonicalize(value) {
   return value;
 }
 
+function rejectRetiredCitationKeys(value, errors) {
+  for (const [group, claims] of [
+    ['claims', value?.claims],
+    ['unresolvedClaims', value?.unresolvedClaims],
+  ]) {
+    for (const [claimIndex, claim] of (claims ?? []).entries()) {
+      for (const [citationIndex, citation] of (
+        claim?.citations ?? []
+      ).entries()) {
+        for (const key of [
+          'repository',
+          'revision',
+          'path',
+          'lineRange',
+          'url',
+        ]) {
+          if (citation?.[key] !== undefined) {
+            add(
+              errors,
+              `$.${group}[${claimIndex}].citations[${citationIndex}].${key}`,
+              'unknown-key',
+              `Unknown property ${key}.`,
+            );
+          }
+        }
+      }
+    }
+  }
+}
+
+function validateManifest(value, errors) {
+  const immutableHashes = isObject(value?.immutableHashes)
+    ? value.immutableHashes
+    : {};
+  if (
+    typeof value?.theme?.path === 'string' &&
+    !(value.theme.path in immutableHashes)
+  ) {
+    add(
+      errors,
+      '$.theme.path',
+      'immutable-package-incomplete',
+      'Theme path must be covered by immutable hashes.',
+    );
+  }
+  if (
+    typeof value?.theme?.hash === 'string' &&
+    value.theme.hash !== immutableHashes['theme.resolved.json']
+  ) {
+    add(
+      errors,
+      '$.theme.hash',
+      'hash-mismatch',
+      'Theme hash must match theme.resolved.json.',
+    );
+  }
+  for (const [index, artifact] of (value?.artifacts ?? []).entries()) {
+    if (
+      typeof artifact?.contentPath === 'string' &&
+      !(artifact.contentPath in immutableHashes)
+    ) {
+      add(
+        errors,
+        `$.artifacts[${index}].contentPath`,
+        'immutable-package-incomplete',
+        'Artifact content path must be covered by immutable hashes.',
+      );
+    }
+    if (
+      typeof artifact?.hash === 'string' &&
+      artifact.hash !== immutableHashes[artifact.contentPath]
+    ) {
+      add(
+        errors,
+        `$.artifacts[${index}].hash`,
+        'hash-mismatch',
+        'Artifact hash must match its immutable content hash.',
+      );
+    }
+  }
+}
+
 function validateSchema(schema, value, path, rootSchema, errors) {
   if (schema.$ref) {
     if (schema.$ref.endsWith('/safeRelativePath')) {
@@ -235,10 +180,8 @@ function validateSchema(schema, value, path, rootSchema, errors) {
     validateSchema(resolved.schema, value, path, resolved.root, errors);
   }
 
-  if (schema.allOf) {
-    for (const child of schema.allOf) {
-      validateSchema(child, value, path, rootSchema, errors);
-    }
+  for (const child of schema.allOf ?? []) {
+    validateSchema(child, value, path, rootSchema, errors);
   }
 
   if (schema.oneOf) {
@@ -368,9 +311,7 @@ function validateSchema(schema, value, path, rootSchema, errors) {
       }
     }
     for (const [key, childValue] of Object.entries(value)) {
-      if (key in properties) {
-        continue;
-      }
+      if (key in properties) continue;
       if (schema.additionalProperties === false) {
         add(
           errors,
@@ -403,193 +344,20 @@ function validateSchema(schema, value, path, rootSchema, errors) {
 }
 
 function validateContractPaths(kind, value, errors) {
-  if (!isObject(value)) {
-    return;
-  }
-
-  if (kind === 'run-request') {
-    addLexicalPathErrors(value.outputRoot, '$.outputRoot', errors, true);
-    if (isObject(value.factBase)) {
-      addLexicalPathErrors(
-        value.factBase.path,
-        '$.factBase.path',
-        errors,
-        true,
-      );
-    }
-    if (isObject(value.theme)) {
-      addLexicalPathErrors(
-        value.theme.suppliedBundlePath,
-        '$.theme.suppliedBundlePath',
-        errors,
-        true,
-      );
-    }
-    if (isObject(value.durability) && isObject(value.durability.publish)) {
-      validateContractPaths(
-        'publish-request',
-        value.durability.publish,
-        errors,
-      );
-    }
-  }
-
-  if (kind === 'publish-request') {
-    addLexicalPathErrors(value.siteRoot, '$.siteRoot', errors, true);
-    addLexicalPathErrors(value.manifestPath, '$.manifestPath', errors, true);
-  }
-
-  if (kind === 'durability-evidence') {
-    addLexicalPathErrors(value.manifestPath, '$.manifestPath', errors, true);
-    if (isObject(value.evidence)) {
-      addLexicalPathErrors(
-        value.evidence.repoRoot,
-        '$.evidence.repoRoot',
-        errors,
-        true,
-      );
-      addLexicalPathErrors(
-        value.evidence.receiptPath,
-        '$.evidence.receiptPath',
-        errors,
-        true,
-      );
-      if (Array.isArray(value.evidence.paths)) {
-        value.evidence.paths.forEach((candidate, index) =>
-          addLexicalPathErrors(
-            candidate,
-            `$.evidence.paths[${index}]`,
-            errors,
-            false,
-          ),
-        );
-      }
-    }
-  }
-
-  if (kind === 'manifest' && Array.isArray(value.artifacts)) {
-    value.artifacts.forEach((artifact, index) => {
-      if (isObject(artifact) && isObject(artifact.rebuild)) {
-        addLexicalPathErrors(
-          artifact.rebuild.cwd,
-          `$.artifacts[${index}].rebuild.cwd`,
-          errors,
-          true,
-        );
-      }
-    });
-  }
-}
-
-function validatePublicationRoots(kind, value, errors, path = '$') {
-  if (!isObject(value)) return;
-
-  if (kind === 'run-request') {
-    const publish = value.durability?.publish;
-    if (isObject(publish)) {
-      validatePublicationRoots(
-        'publish-request',
-        publish,
-        errors,
-        `${path}.durability.publish`,
-      );
-    }
-    return;
-  }
-
-  // Default-deny: every publish-request shape is validated, regardless of its
-  // declared schemaVersion. Keying this gate to an exact version string is what
-  // let `publish-request/v1` reach `initializeRun` with credential-bearing roots,
-  // and would let any future version reintroduce the same bypass.
-  if (kind.startsWith('publish-request')) {
-    try {
-      normalizePublishRoots(value.s3Uri, value.publicBaseUrl);
-    } catch {
-      add(
-        errors,
-        path,
-        'publish-roots',
-        'Publish request roots must be credential-free and canonical.',
-      );
-    }
+  if (
+    !isObject(value) ||
+    (kind !== 'manifest' && kind !== 'explainer-kit.manifest/v1')
+  ) {
     return;
   }
-
-  if (kind.startsWith('publish-receipt')) {
-    // Same default-deny rule as the request branch above: every receipt shape
-    // has its roots screened, whatever version it declares. Pinning this to the
-    // exact v2 string let a `publish-receipt/v1` carry credential-bearing and
-    // internal-address roots straight through to `publish-receipt.json`, a
-    // retained hash-covered member of the run package, and on into the
-    // `publish-summary/v1` projection.
-    const receiptV2 = isVerifiablePublishReceipt(value);
-    let roots;
-    try {
-      roots = normalizePublishRoots(
-        value.roots?.s3Uri,
-        value.roots?.publicBaseUrl,
-      );
-      // The stricter *canonical-form* assertion stays v2-only: v1 is retained
-      // purely for replay and may legitimately carry non-canonical historical
-      // forms such as trailing slashes. Credential and address screening above
-      // applies to both, because no replay need justifies either.
-      if (
-        receiptV2 &&
-        (roots.s3Uri !== value.roots.s3Uri ||
-          roots.publicBaseUrl !== value.roots.publicBaseUrl)
-      ) {
-        throw new Error('noncanonical');
-      }
-    } catch {
-      add(
-        errors,
-        `${path}.roots`,
-        'publish-roots',
-        'Publish receipt roots must be credential-free and canonical.',
-      );
-      return;
-    }
-
-    if (!receiptV2) return;
-
-    for (const [index, artifact] of (Array.isArray(value.artifacts)
-      ? value.artifacts
-      : []
-    ).entries()) {
-      if (!isObject(artifact) || typeof artifact.relativePath !== 'string') {
-        continue;
-      }
-      const publishPath = artifact.relativePath.startsWith('site/')
-        ? artifact.relativePath.slice('site/'.length)
-        : artifact.relativePath;
-      try {
-        const expected = composePublicationTarget(publishPath, roots);
-        if (
-          artifact.s3Uri !== expected.s3Uri ||
-          artifact.publicUrl !== expected.publicUrl
-        ) {
-          throw new Error('destination mismatch');
-        }
-      } catch {
-        add(
-          errors,
-          `${path}.artifacts[${index}]`,
-          'receipt-artifact-destination',
-          'Publish receipt artifact destinations must be canonical children of the validated roots.',
-        );
-      }
-    }
+  for (const [path, hash] of Object.entries(value.immutableHashes ?? {})) {
+    addLexicalPathErrors(path, `$.immutableHashes.${path}`, errors, false);
+    if (typeof hash !== 'string') continue;
   }
 }
 
 function addLexicalPathErrors(value, path, errors, allowAbsolute) {
-  if (value === undefined) {
-    return;
-  }
-  if (typeof value !== 'string') {
-    return;
-  }
-
+  if (value === undefined || typeof value !== 'string') return;
   const result = validatePortablePath(value, { allowAbsolute });
   if (!result.valid) {
     add(errors, path, 'unsafe-path', result.errors[0].message);
@@ -603,1180 +371,21 @@ function resolveReference(reference, rootSchema) {
       .split('/')
       .map((part) => part.replaceAll('~1', '/').replaceAll('~0', '~'));
     let schema = rootSchema;
-    for (const part of parts) {
-      schema = schema?.[part];
-    }
+    for (const part of parts) schema = schema?.[part];
     return schema ? { schema, root: rootSchema } : null;
   }
   const external = SCHEMAS_BY_ID.get(reference);
   return external ? { schema: external, root: external } : null;
 }
 
-function validateCrossRecord(kind, value, context, errors) {
-  if (!isObject(value)) {
-    return;
-  }
-
-  if (kind === 'run-request') {
-    const factBase = value.factBase;
-    if (isObject(factBase)) {
-      const hasPath = typeof factBase.path === 'string';
-      const hasSources = Array.isArray(factBase.sources);
-      if (
-        (factBase.mode === 'supplied' && (!hasPath || hasSources)) ||
-        (factBase.mode === 'federated' && (!hasSources || hasPath))
-      ) {
-        add(
-          errors,
-          '$.factBase',
-          'fact-base-fields',
-          'Supplied fact bases require only path; federated fact bases require only sources.',
-        );
-      }
-    }
-
-    const durability = value.durability;
-    if (
-      isObject(durability) &&
-      durability.strategy === 'publish' &&
-      !isObject(durability.publish)
-    ) {
-      add(
-        errors,
-        '$.durability.publish',
-        'incomplete-publish',
-        'Publish durability requires a complete publish request.',
-      );
-    }
-    if (
-      isObject(durability) &&
-      durability.strategy !== 'publish' &&
-      'publish' in durability
-    ) {
-      add(
-        errors,
-        '$.durability.publish',
-        'unexpected-publish',
-        'Publish settings are allowed only for publish durability.',
-      );
-    }
-
-    if (
-      isObject(value.privacy) &&
-      value.privacy.retainRawArtDirection === true &&
-      (!isObject(value.theme) ||
-        typeof value.theme.artDirection !== 'string' ||
-        value.theme.artDirection.length === 0)
-    ) {
-      add(
-        errors,
-        '$.privacy.retainRawArtDirection',
-        'art-direction-required',
-        'Retaining raw art direction requires theme.artDirection.',
-      );
-    }
-
-    if (value.recapMode !== undefined && value.recipe?.id !== 'project-recap') {
-      add(
-        errors,
-        '$.recapMode',
-        'recap-mode-recipe',
-        'recapMode is allowed only for the project-recap recipe.',
-      );
-    }
-  }
-
-  if (kind === 'set-plan') {
-    validateSetPlan(value, errors);
-  }
-
-  if (
-    ['author-request', 'author-request/v2', 'author-request/v3'].includes(
-      kind,
-    ) ||
-    [
-      'explainer-kit.author-request/v2',
-      'explainer-kit.author-request/v3',
-    ].includes(value.schemaVersion)
-  ) {
-    validateAuthorSetContext(value, errors);
-    validateVisualAuthoringGuidance(value, errors);
-    validateAuthorGraphSemantics(value, errors);
-    if (value.schemaVersion === 'explainer-kit.author-request/v3') {
-      validateAuthorArtifactLinks(value, errors);
-    }
-  }
-
-  if (kind === 'visual-review-request') {
-    if (
-      typeof value.requestHash === 'string' &&
-      value.requestHash !== canonicalHash(visualReviewRequestPayload(value))
-    ) {
-      add(
-        errors,
-        '$.requestHash',
-        'request-hash-mismatch',
-        'Visual review request hash does not match its canonical evidence payload.',
-      );
-    }
-    if (
-      typeof value.requestHash === 'string' &&
-      typeof value.requestId === 'string' &&
-      value.requestId !== visualReviewRequestId(value.requestHash)
-    ) {
-      add(
-        errors,
-        '$.requestId',
-        'request-id-mismatch',
-        'Visual review request identity does not match its canonical request hash.',
-      );
-    }
-    const plannedArtifactIds = Array.isArray(value.plan?.portfolio)
-      ? value.plan.portfolio.map(({ artifactId }) => artifactId)
-      : [];
-    const plannedIds = new Set(plannedArtifactIds);
-    const renderedIds = new Set();
-    const requiresObservedCohesion = value.plan?.recipe?.id === 'project-recap';
-    const expectedCohesion = expectedLedgerClaims(value.plan?.ledger);
-    const observedCohesion = new Set();
-    if (
-      requiresObservedCohesion &&
-      ['terminology', 'statuses', 'numericClaims'].some(
-        (group) => expectedCohesion[group].size === 0,
-      )
-    ) {
-      add(
-        errors,
-        '$.plan.ledger',
-        'cohesion-ledger-empty',
-        'Adaptive recap review requires non-empty terminology, status, and numeric ledger entries.',
-      );
-    }
-    for (const [index, artifact] of (Array.isArray(value.renderedArtifacts)
-      ? value.renderedArtifacts
-      : []
-    ).entries()) {
-      for (const [evidenceIndex, evidence] of (Array.isArray(artifact?.evidence)
-        ? artifact.evidence
-        : []
-      ).entries()) {
-        if (evidence?.captureIdentity !== value.captureIdentity) {
-          add(
-            errors,
-            `$.renderedArtifacts[${index}].evidence[${evidenceIndex}].captureIdentity`,
-            'browser-runtime-mismatch',
-            'Every visual-review evidence record must bind the request browser capture identity.',
-          );
-        }
-      }
-      if (!plannedIds.has(artifact?.artifactId)) {
-        add(
-          errors,
-          `$.renderedArtifacts[${index}].artifactId`,
-          'unknown-artifact',
-          'Rendered artifact is not present in the shared set plan.',
-        );
-      }
-      if (renderedIds.has(artifact?.artifactId)) {
-        add(
-          errors,
-          `$.renderedArtifacts[${index}].artifactId`,
-          'duplicate-artifact',
-          'Rendered artifact IDs must be unique.',
-        );
-      }
-      renderedIds.add(artifact?.artifactId);
-      const observations = Array.isArray(artifact?.cohesionObservations)
-        ? artifact.cohesionObservations
-        : [];
-      if (requiresObservedCohesion && observations.length === 0) {
-        add(
-          errors,
-          `$.renderedArtifacts[${index}].cohesionObservations`,
-          'cohesion-observations-empty',
-          'Every adaptive recap artifact must expose observed shared-ledger evidence.',
-        );
-      }
-      for (const [observationIndex, observation] of observations.entries()) {
-        if (
-          observation?.artifactId !== artifact?.artifactId ||
-          observation?.contentHash !== artifact?.renderedHash
-        ) {
-          add(
-            errors,
-            `$.renderedArtifacts[${index}].cohesionObservations[${observationIndex}]`,
-            'cohesion-binding-mismatch',
-            'Cohesion observations must bind to their artifact and exact rendered content hash.',
-          );
-          continue;
-        }
-        const expected = expectedCohesion[observation.group]?.get(
-          observation.claim,
-        );
-        if (
-          expected === undefined ||
-          normalizeComparable(expected) !==
-            normalizeComparable(observation.value)
-        ) {
-          add(
-            errors,
-            `$.renderedArtifacts[${index}].cohesionObservations[${observationIndex}]`,
-            'cohesion-contradiction',
-            'Observed cohesion evidence must match an applicable shared-ledger value.',
-          );
-          continue;
-        }
-        observedCohesion.add(`${observation.group}:${observation.claim}`);
-      }
-    }
-    for (const artifactId of plannedArtifactIds) {
-      if (!renderedIds.has(artifactId)) {
-        add(
-          errors,
-          '$.renderedArtifacts',
-          'missing-artifact',
-          `Rendered review set is missing planned artifact ${artifactId}.`,
-        );
-      }
-    }
-    if (requiresObservedCohesion) {
-      for (const [group, claims] of Object.entries(expectedCohesion)) {
-        for (const claim of claims.keys()) {
-          if (!observedCohesion.has(`${group}:${claim}`)) {
-            add(
-              errors,
-              '$.renderedArtifacts',
-              'cohesion-claim-unobserved',
-              `Shared-ledger claim ${group}.${claim} is not observable in the rendered set.`,
-            );
-          }
-        }
-      }
-    }
-  }
-
-  if (kind === 'visual-review-result') {
-    const reviewRequest = context.visualReviewRequest;
-    if (!isObject(reviewRequest)) {
-      add(
-        errors,
-        '$',
-        'review-request-required',
-        'Visual review results must be validated with their reviewed request.',
-      );
-      return;
-    }
-
-    const requestValidation = validateContract(
-      'visual-review-request',
-      reviewRequest,
-    );
-    if (!requestValidation.valid) {
-      add(
-        errors,
-        '$',
-        'invalid-review-request',
-        'Visual review result cannot bind to an invalid reviewed request.',
-      );
-    }
-    if (
-      value.requestId !== reviewRequest.requestId ||
-      value.requestHash !== reviewRequest.requestHash
-    ) {
-      add(
-        errors,
-        '$.requestHash',
-        'review-binding-mismatch',
-        'Visual review result must echo the exact reviewed request identity and hash.',
-      );
-    }
-
-    const reviewedArtifactIds = Array.isArray(reviewRequest.renderedArtifacts)
-      ? reviewRequest.renderedArtifacts.map(({ artifactId }) => artifactId)
-      : [];
-    const reviewedIds = new Set(reviewedArtifactIds);
-    const resultArtifactIds = Array.isArray(value.artifactIds)
-      ? value.artifactIds
-      : [];
-    const resultIds = new Set(resultArtifactIds);
-    if (
-      resultIds.size !== reviewedIds.size ||
-      reviewedArtifactIds.some((artifactId) => !resultIds.has(artifactId))
-    ) {
-      add(
-        errors,
-        '$.artifactIds',
-        'review-set-mismatch',
-        'Visual review result artifact IDs must equal the complete reviewed request set.',
-      );
-    }
-    for (const [index, finding] of (Array.isArray(value.findings)
-      ? value.findings
-      : []
-    ).entries()) {
-      if (!reviewedIds.has(finding?.artifactId)) {
-        add(
-          errors,
-          `$.findings[${index}].artifactId`,
-          'detached-finding',
-          'Visual review findings must reference an artifact in the reviewed request.',
-        );
-      }
-    }
-    const findingCount = Array.isArray(value.findings)
-      ? value.findings.length
-      : 0;
-    if (
-      (value.disposition === 'pass' && findingCount > 0) ||
-      (['correct', 'fail'].includes(value.disposition) && findingCount === 0)
-    ) {
-      add(
-        errors,
-        '$.disposition',
-        'disposition-findings-mismatch',
-        'Pass requires no findings; correct and fail require at least one correction finding.',
-      );
-    }
-  }
-
-  if (kind === 'terminal-evidence') {
-    validateTerminalEvidence(value, context.manifest, errors);
-  }
-
-  if (kind === 'visual-review-evidence') {
-    validateVisualReviewEvidence(
-      value,
-      context.visualReviewRequest,
-      context.attempt,
-      errors,
-    );
-  }
-
-  if (kind === 'manifest') {
-    const paths = [];
-    for (const artifact of Array.isArray(value.artifacts)
-      ? value.artifacts
-      : []) {
-      if (!isObject(artifact)) {
-        continue;
-      }
-      for (const field of ['contentPath', 'renderedPath']) {
-        if (typeof artifact[field] === 'string') {
-          paths.push(artifact[field]);
-        }
-      }
-      if (artifact.status === 'built' && typeof artifact.hash !== 'string') {
-        add(
-          errors,
-          '$.artifacts',
-          'built-artifact-hash-required',
-          'Built artifacts require a canonical hash.',
-        );
-      }
-      if (artifact.rebuildable === true && !isObject(artifact.rebuild)) {
-        add(
-          errors,
-          '$.artifacts',
-          'rebuild-metadata-required',
-          'Rebuildable artifacts require rebuild metadata.',
-        );
-      }
-      if (
-        value.outcome === 'built-durable' &&
-        artifact.status === 'built' &&
-        (!Array.isArray(artifact.durableEvidence) ||
-          artifact.durableEvidence.length === 0)
-      ) {
-        add(
-          errors,
-          '$.artifacts',
-          'durability-evidence-required',
-          'Durable built artifacts require durability evidence.',
-        );
-      }
-    }
-    if (new Set(paths).size !== paths.length) {
-      add(
-        errors,
-        '$.artifacts',
-        'duplicate-artifact-path',
-        'Artifact content and rendered paths must be unique.',
-      );
-    }
-
-    const requiredProvenance = [
-      'run-request.json',
-      'source/content-approval.json',
-    ];
-    const recordedImmutable = isObject(value.immutableHashes)
-      ? new Set(Object.keys(value.immutableHashes))
-      : new Set();
-    const retainsSetPlan =
-      value.recipe?.id === 'project-recap' ||
-      SET_PLAN_RECORD_PATHS.some((path) => recordedImmutable.has(path));
-    const expectedImmutable = new Set([
-      ...requiredProvenance,
-      value.source?.factBasePath,
-      'source/fact-base.md',
-      ...(retainsSetPlan ? SET_PLAN_RECORD_PATHS : []),
-      ...(Array.isArray(value.source?.authorResultPaths)
-        ? value.source.authorResultPaths
-        : []),
-      value.theme?.path,
-      ...(Array.isArray(value.artifacts)
-        ? value.artifacts.flatMap((artifact) => [
-            artifact?.contentPath,
-            ...(artifact?.status === 'built' &&
-            typeof artifact?.renderedPath === 'string'
-              ? [artifact.renderedPath]
-              : []),
-          ])
-        : []),
-    ]);
-    expectedImmutable.delete(undefined);
-    const missingLegacyPaths = requiredProvenance.filter(
-      (path) => !recordedImmutable.has(path),
-    );
-    if (missingLegacyPaths.length > 0) {
-      add(
-        errors,
-        '$.immutableHashes',
-        'legacy-manifest-incomplete',
-        `Legacy manifest is missing immutable coverage for ${missingLegacyPaths.join(', ')}; regenerate the recap package before archival.`,
-      );
-    }
-    if ([...expectedImmutable].some((path) => !recordedImmutable.has(path))) {
-      add(
-        errors,
-        '$.immutableHashes',
-        'immutable-package-incomplete',
-        'Manifest immutable hashes must cover the complete retained fact-base, set plan, content, theme, and required built artifact package.',
-      );
-    }
-    const hasVisualEvidence = [...recordedImmutable].some((path) =>
-      path.startsWith('qa/visual-review/'),
-    );
-    if (
-      hasVisualEvidence &&
-      [
-        'qa/visual-review/attempt-1/request.json',
-        'qa/visual-review/attempt-1/result.json',
-      ].some((path) => !recordedImmutable.has(path))
-    ) {
-      add(
-        errors,
-        '$.immutableHashes',
-        'visual-review-chain-incomplete',
-        'Retained visual review evidence requires its bound attempt request and result.',
-      );
-    }
-    for (const path of recordedImmutable) {
-      if (
-        (path.startsWith('qa/browser/') ||
-          path.includes('/visual-review/attempt-')) &&
-        path.endsWith('.png') &&
-        !recordedImmutable.has(path.replace(/\.png$/, '.json'))
-      ) {
-        add(
-          errors,
-          '$.immutableHashes',
-          'visual-review-chain-incomplete',
-          `Screenshot evidence ${path} is missing its immutable metrics record.`,
-        );
-      }
-    }
-
-    const record = context.buildRecord;
-    if (isObject(record)) {
-      if (value.runId !== record.runId || value.outcome !== record.outcome) {
-        add(
-          errors,
-          '$',
-          'cross-record-mismatch',
-          'Manifest and build record identity or outcome do not match.',
-        );
-      }
-      if (
-        isObject(value.buildRecord) &&
-        value.buildRecord.hash !== canonicalHash(record)
-      ) {
-        add(
-          errors,
-          '$.buildRecord.hash',
-          'hash-mismatch',
-          'Build record hash does not match canonical content.',
-        );
-      }
-    }
-    if (
-      isObject(context.theme) &&
-      isObject(value.theme) &&
-      value.theme.hash !== canonicalHash(context.theme)
-    ) {
-      add(
-        errors,
-        '$.theme.hash',
-        'hash-mismatch',
-        'Theme hash does not match canonical content.',
-      );
-    }
-    if (isObject(context.runRequest) && isObject(record)) {
-      const expected =
-        isObject(context.runRequest.theme) &&
-        typeof context.runRequest.theme.renderStrategy === 'string'
-          ? context.runRequest.theme.renderStrategy
-          : 'default-only';
-      if (record.renderStrategy !== expected) {
-        add(
-          errors,
-          '$.renderStrategy',
-          'cross-record-mismatch',
-          'Build render strategy does not match the run request.',
-        );
-      }
-    }
-  }
-
-  if (kind.startsWith('publish-receipt') && isVerifiablePublishReceipt(value)) {
-    const sentinel = value.sentinel;
-    if (
-      sentinel?.objectVerification?.status !== 'verified' ||
-      sentinel.objectVerification.hash === undefined
-    ) {
-      add(
-        errors,
-        '$.sentinel.objectVerification',
-        'receipt-object-verification',
-        'Publish receipt sentinel requires exact authenticated object verification.',
-      );
-    }
-    const validPublic =
-      value.publicAccess === 'public'
-        ? sentinel?.publicVerification?.status === 'verified' &&
-          sentinel.publicVerification.hash === sentinel.objectVerification?.hash
-        : sentinel?.publicVerification?.status === 'skipped-protected';
-    if (!validPublic) {
-      add(
-        errors,
-        '$.sentinel.publicVerification',
-        'receipt-public-verification',
-        'Publish receipt sentinel public verification must match the declared public-access mode.',
-      );
-    }
-  }
-
-  if (
-    kind === 'publish-receipt' &&
-    isObject(context.manifest) &&
-    Array.isArray(value.artifacts)
-  ) {
-    const expected = new Map();
-    for (const artifact of context.manifest.artifacts ?? []) {
-      if (
-        isObject(artifact) &&
-        artifact.status === 'built' &&
-        typeof artifact.renderedPath === 'string'
-      ) {
-        expected.set(artifact.renderedPath, {
-          hash: artifact.hash,
-          source: { kind: 'manifest', artifactId: artifact.id },
-        });
-      }
-    }
-    if (
-      isObject(context.catalogArtifact) &&
-      typeof context.catalogArtifact.relativePath === 'string'
-    ) {
-      expected.set(context.catalogArtifact.relativePath, {
-        hash: context.catalogArtifact.hash,
-        source: { kind: 'auxiliary', name: 'catalog' },
-      });
-    }
-    const received = new Set();
-    for (const artifact of value.artifacts) {
-      const expectedArtifact = expected.get(artifact?.relativePath);
-      if (isObject(artifact) && expectedArtifact?.hash !== artifact.hash) {
-        add(
-          errors,
-          '$.artifacts',
-          'cross-record-mismatch',
-          'Publish receipt artifact does not match the manifest.',
-        );
-      }
-      if (isVerifiablePublishReceipt(value) && isObject(artifact)) {
-        validatePublishReceiptV2Artifact(
-          value,
-          artifact,
-          expectedArtifact,
-          errors,
-        );
-      }
-      if (received.has(artifact?.relativePath)) {
-        add(
-          errors,
-          '$.artifacts',
-          'receipt-artifact-parity',
-          'Publish receipt artifact paths must be unique.',
-        );
-      }
-      received.add(artifact?.relativePath);
-    }
-    if (
-      received.size !== expected.size ||
-      [...expected.keys()].some((path) => !received.has(path))
-    ) {
-      add(
-        errors,
-        '$.artifacts',
-        'receipt-artifact-parity',
-        'Publish receipt must exactly cover every manifest artifact and the generated catalog.',
-      );
-    }
-  }
-}
-
-function validateTerminalEvidence(value, manifest, errors) {
-  const reasons = Array.isArray(value.reasons) ? value.reasons : [];
-  const artifactIds = isObject(manifest)
-    ? new Set(
-        (Array.isArray(manifest.artifacts) ? manifest.artifacts : []).map(
-          ({ id }) => id,
-        ),
-      )
-    : null;
-  validateReasonSet(reasons, artifactIds, '$.reasons', errors);
-
-  if (isObject(manifest)) {
-    if (value.runId !== manifest.runId) {
-      add(
-        errors,
-        '$.runId',
-        'terminal-run-mismatch',
-        'Terminal evidence run identity must match its manifest.',
-      );
-    }
-    if (value.outcome !== manifest.outcome) {
-      add(
-        errors,
-        '$.outcome',
-        'terminal-outcome-mismatch',
-        'Terminal evidence outcome must match its manifest.',
-      );
-    }
-    if (value.manifestHash !== canonicalHash(manifest)) {
-      add(
-        errors,
-        '$.manifestHash',
-        'terminal-manifest-mismatch',
-        'Terminal evidence manifest hash must match its manifest.',
-      );
-    }
-  }
-
-  if (value.evidenceDisposition === 'superseded') {
-    const reason = reasons[0];
-    if (
-      reasons.length !== 1 ||
-      reason?.stage !== 'finalization' ||
-      reason?.kind !== 'superseded' ||
-      reason?.count !== 1 ||
-      reason?.artifactId !== undefined
-    ) {
-      add(
-        errors,
-        '$.reasons',
-        'supersession-reason',
-        'Superseded evidence requires exactly one count-1 finalization/superseded reason without an artifact ID.',
-      );
-    }
-    if (
-      !isObject(value.supersededBy) ||
-      value.supersededBy.runId === value.runId
-    ) {
-      add(
-        errors,
-        '$.supersededBy',
-        'supersession-binding',
-        'Superseded evidence requires a distinct replacement run identity.',
-      );
-    }
-    if (typeof value.manifestHash !== 'string') {
-      add(
-        errors,
-        '$.manifestHash',
-        'supersession-manifest',
-        'Superseded evidence requires the original manifest hash.',
-      );
-    }
-    return;
-  }
-
-  if (value.supersededBy !== undefined) {
-    add(
-      errors,
-      '$.supersededBy',
-      'unexpected-supersession',
-      'Only superseded evidence may identify a replacement run.',
-    );
-  }
-  if (reasons.some((reason) => reason?.kind === 'superseded')) {
-    add(
-      errors,
-      '$.reasons',
-      'unexpected-supersession',
-      'Only superseded evidence may contain a superseded reason.',
-    );
-  }
-  const allowedKinds =
-    value.outcome === 'failed'
-      ? new Set(['provider-failure', 'pipeline-failure'])
-      : new Set(['finding', 'provider-failure', 'pipeline-failure']);
-  if (!reasons.some((reason) => allowedKinds.has(reason?.kind))) {
-    add(
-      errors,
-      '$.reasons',
-      'terminal-outcome-reasons',
-      'Terminal evidence reasons do not satisfy the terminal outcome.',
-    );
-  }
-}
-
-function validateVisualReviewEvidence(value, request, attempt, errors) {
-  if (!isObject(request)) {
-    add(
-      errors,
-      '$',
-      'review-request-required',
-      'Retained visual evidence requires its adjacent reviewed request.',
-    );
-    return;
-  }
-  const requestValidation = validateContract('visual-review-request', request);
-  if (!requestValidation.valid) {
-    add(
-      errors,
-      '$',
-      'invalid-review-request',
-      'Retained visual evidence cannot bind to an invalid reviewed request.',
-    );
-  }
-  if (value.requestHash !== request.requestHash) {
-    add(
-      errors,
-      '$.requestHash',
-      'review-binding-mismatch',
-      'Retained visual evidence must bind the adjacent request hash.',
-    );
-  }
-  if (![1, 2].includes(attempt) || value.attempt !== attempt) {
-    add(
-      errors,
-      '$.attempt',
-      'review-attempt-mismatch',
-      'Retained visual evidence attempt must match its attempt directory.',
-    );
-  }
-
-  const reasons = Array.isArray(value.reasons) ? value.reasons : [];
-  const artifactIds = new Set(
-    (Array.isArray(request.renderedArtifacts)
-      ? request.renderedArtifacts
-      : []
-    ).map(({ artifactId }) => artifactId),
-  );
-  validateReasonSet(reasons, artifactIds, '$.reasons', errors);
-  if (reasons.some((reason) => reason?.stage !== 'visual-review')) {
-    add(
-      errors,
-      '$.reasons',
-      'visual-reason-stage',
-      'Retained visual evidence reasons must use the visual-review stage.',
-    );
-  }
-  const validDisposition =
-    (value.disposition === 'pass' && reasons.length === 0) ||
-    (value.disposition === 'correct' &&
-      reasons.length > 0 &&
-      reasons.every((reason) => reason?.kind === 'finding')) ||
-    (value.disposition === 'failed' &&
-      reasons.length > 0 &&
-      reasons.every((reason) =>
-        ['provider-failure', 'pipeline-failure'].includes(reason?.kind),
-      ));
-  if (!validDisposition) {
-    add(
-      errors,
-      '$.reasons',
-      'visual-disposition-reasons',
-      'Retained visual evidence reasons do not satisfy its disposition.',
-    );
-  }
-}
-
-function validateReasonSet(reasons, artifactIds, path, errors) {
-  let total = 0;
-  const tuples = new Set();
-  for (const [index, reason] of reasons.entries()) {
-    if (!isObject(reason)) continue;
-    if (Number.isInteger(reason.count)) total += reason.count;
-    const tuple = `${reason.stage}\0${reason.kind}\0${reason.artifactId ?? ''}`;
-    if (tuples.has(tuple)) {
-      add(
-        errors,
-        `${path}[${index}]`,
-        'duplicate-reason',
-        'Retained reason tuples must be unique.',
-      );
-    }
-    tuples.add(tuple);
-    if (
-      reason.artifactId !== undefined &&
-      artifactIds &&
-      !artifactIds.has(reason.artifactId)
-    ) {
-      add(
-        errors,
-        `${path}[${index}].artifactId`,
-        'foreign-artifact',
-        'Retained reason artifact IDs must belong to the bound run.',
-      );
-    }
-  }
-  if (total > 50) {
-    add(
-      errors,
-      path,
-      'reason-total',
-      'Retained reason counts must total at most 50.',
-    );
-  }
-}
-
-function validatePublishReceiptV2Artifact(receipt, artifact, expected, errors) {
-  if (!expected || !deepEqual(artifact.source, expected.source)) {
-    add(
-      errors,
-      '$.artifacts',
-      'receipt-artifact-source',
-      'Publish receipt source identity does not match the manifest or generated auxiliary object.',
-    );
-  }
-  if (
-    artifact.objectVerification?.status !== 'verified' ||
-    artifact.objectVerification?.hash !== artifact.hash
-  ) {
-    add(
-      errors,
-      '$.artifacts',
-      'receipt-object-verification',
-      'Publish receipt object verification must prove the exact artifact hash.',
-    );
-  }
-  const publicVerification = artifact.publicVerification;
-  const validPublic =
-    receipt.publicAccess === 'public'
-      ? publicVerification?.status === 'verified' &&
-        publicVerification?.hash === artifact.hash
-      : publicVerification?.status === 'skipped-protected';
-  if (!validPublic) {
-    add(
-      errors,
-      '$.artifacts',
-      'receipt-public-verification',
-      'Publish receipt public verification must match the declared public-access mode.',
-    );
-  }
-}
-
-export function visualReviewRequestPayload(request) {
-  const {
-    requestId: _requestId,
-    requestHash: _requestHash,
-    ...payload
-  } = request;
-  return payload;
-}
-
-export function visualReviewRequestId(requestHash) {
-  return `visual-review-${String(requestHash).replace(/^sha256:/, '')}`;
-}
-
-function expectedLedgerClaims(ledger) {
-  return {
-    terminology: new Map(
-      (ledger?.terminology ?? []).map(({ term }) => [term, term]),
-    ),
-    statuses: new Map(
-      (ledger?.statuses ?? []).map(({ subject, value }) => [subject, value]),
-    ),
-    numericClaims: new Map(
-      (ledger?.numbers ?? []).map(({ subject, value }) => [subject, value]),
-    ),
-  };
-}
-
-function normalizeComparable(value) {
-  return String(value).trim().toLocaleLowerCase();
-}
-
-function validateSetPlan(value, errors) {
-  const sourceIds = new Set(
-    Array.isArray(value.sourceIds) ? value.sourceIds : [],
-  );
-  const artifactIds = new Set();
-  for (const [index, artifact] of (Array.isArray(value.portfolio)
-    ? value.portfolio
-    : []
-  ).entries()) {
-    if (artifactIds.has(artifact?.artifactId)) {
-      add(
-        errors,
-        `$.portfolio[${index}].artifactId`,
-        'duplicate-artifact',
-        'Set-plan artifact IDs must be unique.',
-      );
-    }
-    artifactIds.add(artifact?.artifactId);
-    for (const sourceId of Array.isArray(artifact?.sourceIds)
-      ? artifact.sourceIds
-      : []) {
-      if (!sourceIds.has(sourceId)) {
-        add(
-          errors,
-          `$.portfolio[${index}].sourceIds`,
-          'unknown-source',
-          `Artifact source ${sourceId} is not declared by the set plan.`,
-        );
-      }
-    }
-    if (artifact?.required === false && !isObject(artifact.justification)) {
-      add(
-        errors,
-        `$.portfolio[${index}].justification`,
-        'optional-justification-required',
-        'Optional artifacts require a source-backed justification.',
-      );
-    }
-    for (const sourceId of Array.isArray(artifact?.justification?.sourceIds)
-      ? artifact.justification.sourceIds
-      : []) {
-      if (!sourceIds.has(sourceId) || !artifact.sourceIds?.includes(sourceId)) {
-        add(
-          errors,
-          `$.portfolio[${index}].justification.sourceIds`,
-          'unknown-source',
-          `Justification source ${sourceId} must be declared by the plan and artifact.`,
-        );
-      }
-    }
-  }
-
-  for (const [field, identity] of [
-    ['terminology', (entry) => entry?.term],
-    ['statuses', (entry) => entry?.subject],
-    ['numbers', (entry) => entry?.subject],
-  ]) {
-    const seen = new Map();
-    for (const [index, entry] of (Array.isArray(value.ledger?.[field])
-      ? value.ledger[field]
-      : []
-    ).entries()) {
-      const key = identity(entry);
-      if (
-        seen.has(key) &&
-        canonicalStringify(seen.get(key)) !== canonicalStringify(entry)
-      ) {
-        add(
-          errors,
-          `$.ledger.${field}[${index}]`,
-          'ledger-conflict',
-          `Shared ledger contains conflicting values for ${key}.`,
-        );
-      }
-      seen.set(key, entry);
-    }
-  }
-}
-
-function validateAuthorSetContext(value, errors) {
-  if (!isObject(value.setContext) || !isObject(value.plannedArtifact)) {
-    return;
-  }
-  const planned = Array.isArray(value.setContext.portfolio)
-    ? value.setContext.portfolio.find(
-        ({ artifactId }) => artifactId === value.artifactId,
-      )
-    : undefined;
-  if (
-    !planned ||
-    value.plannedArtifact.artifactId !== value.artifactId ||
-    value.plannedArtifact.artifactType !== value.artifactType
-  ) {
-    add(
-      errors,
-      '$.plannedArtifact',
-      'set-artifact-mismatch',
-      'Author request identity must match one artifact in the shared set plan.',
-    );
-    return;
-  }
-  if (!deepEqual(planned, value.plannedArtifact)) {
-    add(
-      errors,
-      '$.plannedArtifact',
-      'set-plan-drift',
-      'Author request planned artifact must be identical to the shared set plan entry.',
-    );
-  }
-}
-
-function validateAuthorArtifactLinks(value, errors) {
-  if (!Array.isArray(value.artifactLinks) || !isObject(value.setContext)) {
-    return;
-  }
-  const planned = Array.isArray(value.setContext.portfolio)
-    ? value.setContext.portfolio
-    : [];
-  const linksById = new Map();
-  for (const [index, link] of value.artifactLinks.entries()) {
-    if (!isObject(link)) continue;
-    if (linksById.has(link.artifactId)) {
-      add(
-        errors,
-        `$.artifactLinks[${index}].artifactId`,
-        'artifact-link-parity',
-        'Canonical artifact link IDs must be unique.',
-      );
-    }
-    linksById.set(link.artifactId, link);
-  }
-  if (
-    linksById.size !== planned.length ||
-    planned.some(
-      ({ artifactId, artifactType }) =>
-        linksById.get(artifactId)?.artifactType !== artifactType,
-    )
-  ) {
-    add(
-      errors,
-      '$.artifactLinks',
-      'artifact-link-parity',
-      'Canonical artifact links must exactly cover the planned portfolio.',
-    );
-    return;
-  }
-
-  const current = linksById.get(value.artifactId);
-  if (!current || typeof current.sitePath !== 'string') return;
-  const base = new URL(current.sitePath, 'https://explainer.invalid/');
-  for (const [index, link] of value.artifactLinks.entries()) {
-    if (
-      !isObject(link) ||
-      typeof link.href !== 'string' ||
-      typeof link.sitePath !== 'string'
-    ) {
-      continue;
-    }
-    let resolved;
-    try {
-      resolved = new URL(link.href, base);
-    } catch {
-      add(
-        errors,
-        `$.artifactLinks[${index}].href`,
-        'artifact-link-resolution',
-        'Canonical artifact href must be a valid relative reference.',
-      );
-      continue;
-    }
-    if (
-      resolved.origin !== base.origin ||
-      resolved.protocol !== 'https:' ||
-      resolved.username ||
-      resolved.password ||
-      resolved.search ||
-      resolved.hash ||
-      resolved.pathname !== `/${link.sitePath}`
-    ) {
-      add(
-        errors,
-        `$.artifactLinks[${index}].href`,
-        'artifact-link-resolution',
-        'Canonical artifact href must resolve exactly to its declared site path.',
-      );
-    }
-  }
-}
-
-function validateVisualAuthoringGuidance(value, errors) {
-  if (typeof value.visualAuthoringGuidance !== 'string') {
-    return;
-  }
-  const guidance = value.visualAuthoringGuidance.toLowerCase();
-  const missing = [
-    'representation',
-    'hierarchy',
-    'responsive navigation',
-    'table',
-    'diagram',
-    'deck',
-  ].filter((topic) => !guidance.includes(topic));
-  if (missing.length > 0) {
-    add(
-      errors,
-      '$.visualAuthoringGuidance',
-      'malformed-authoring-guidance',
-      `Visual authoring guidance is missing bundled topics: ${missing.join(', ')}.`,
-    );
-  }
-}
-
-function validateAuthorGraphSemantics(value, errors) {
-  if (value.graphSemantics === undefined) {
-    return;
-  }
-  if (value.authoring !== 'html' || !Array.isArray(value.graphSemantics)) {
-    add(
-      errors,
-      '$.graphSemantics',
-      'graph-semantics',
-      'Planner-owned graph semantics are allowed only for artistic HTML authoring.',
-    );
-    return;
-  }
-  for (const [graphIndex, graph] of value.graphSemantics.entries()) {
-    if (!isObject(graph)) continue;
-    const nodes = Array.isArray(graph.nodes) ? graph.nodes : [];
-    const edges = Array.isArray(graph.edges) ? graph.edges : [];
-    const nodeIds = nodes.map(({ id }) => id);
-    const edgeIds = edges.map(({ from, to }) => `${from}\0${to}`);
-    if (
-      new Set(nodeIds).size !== nodeIds.length ||
-      new Set(edgeIds).size !== edgeIds.length ||
-      edges.some(
-        ({ from, to }) => !nodeIds.includes(from) || !nodeIds.includes(to),
-      )
-    ) {
-      add(
-        errors,
-        `$.graphSemantics[${graphIndex}]`,
-        'graph-semantics',
-        'Graph semantics require unique nodes and edges with declared endpoints.',
-      );
-    }
-  }
-}
-
-function findRawSecrets(value, path, errors) {
-  if (Array.isArray(value)) {
-    value.forEach((item, index) =>
-      findRawSecrets(item, `${path}[${index}]`, errors),
-    );
-    return;
-  }
-  if (!isObject(value)) {
+function findRawSecrets(value, path, errors) {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) =>
+      findRawSecrets(item, `${path}[${index}]`, errors),
+    );
     return;
   }
+  if (!isObject(value)) return;
   for (const [key, child] of Object.entries(value)) {
     const normalized = key.toLowerCase().replaceAll(/[^a-z0-9]/g, '');
     if (RAW_SECRET_KEYS.has(normalized)) {