@adea-ai/plugins 4.0.0 → 4.0.6

package/src/index.ts

@@ -1,2562 +1,58 @@
-import { spawn } from 'node:child_process'
-import { createHash } from 'node:crypto'
-import { promises as fs } from 'node:fs'
-import { basename, dirname, join, relative, resolve } from 'node:path'
-import { Readable } from 'node:stream'
-import { setTimeout as sleep } from 'node:timers/promises'
-import { createGunzip } from 'node:zlib'
-import { extract } from 'tar-stream'
-import {
-  CatalogSchema,
-  type Catalog,
-  type CatalogSource,
-  type Capability,
-  type Harness,
-  type HarnessCompatibility,
-  type LicenseMetadata,
-  type Plugin,
-  type PluginRelease,
-  type SecurityClassification,
-  type SourceLockEntry,
-  type SourcesLock,
-  type PluginProvenance,
-  HarnessSchema,
-  SourcesLockSchema,
-  PluginSchema,
-} from './schema.js'
-import {
-  canonicalRepositoryUrl,
-  parseJsonDocument,
-  parseMarketplaceManifest,
-  safeRelativePath,
-  type MarketplacePluginEntry,
-  type ParsedMarketplace,
-  type PluginSourceSpec,
-  type SourceConfig,
-} from './sources.js'
-import {
-  buildConsumerIndex,
-  CATALOG_INDEX_ARTIFACT,
-  iconCoverage,
-  type ConsumerCategory,
-  type ConsumerIndex,
-  type ConsumerProduct,
-  type LeadingDiagnostic,
-  type ProductPreference,
-} from './consumer-index.js'
-import {
-  iconAssetName,
-  iconOverrideFor,
-  inspectIconBytes,
-  selectIconPath,
-  type ProductIconOverrides,
-} from './icons.js'
-import { stageIconBytes } from './icon-mirror.js'
-import {
-  isVendorHomepage,
-  resolveSiteIcon,
-  type SiteIcon,
-  type SiteIconFetcher,
-} from './site-icons.js'
-import { normalizeDisplayName } from './display-name.js'
-import { immutableAssetUrl } from './publication.js'
-import { sourceDigest as bytesDigest } from './source-digest.js'
-
-export { bytesDigest }
-
-/**
- * Marks the catalog format this compiler emits.
- *
- * Bumping or first introducing this value makes a synchronization replay its
- * verified pins and rebuild, which is how a format change reaches the published
- * catalog when no upstream source has moved. It is deliberately separate from
- * the agent-package normalizer version, which describes package normalization
- * and would misreport a change here.
- */
-export const CATALOG_CONTRACT_VERSION = 'adea-catalog/3'
-
-export interface CatalogPolicy {
-  readonly allowedRepositoryProtocols: readonly string[]
-  readonly allowedRepositoryHosts: readonly string[]
-  readonly maxFilesPerPlugin: number
-  readonly maxBytesPerPlugin: number
-  readonly maxFileBytes: number
-  readonly maxMarketplacePlugins: number
-  readonly denyExecutableLifecycleScripts: boolean
-  readonly publishRequiresCompleteContent: boolean
-  readonly sensitiveCapabilityTypes: readonly string[]
-}
-
-export interface CategoryMap {
-  readonly aliases: Readonly<Record<string, string>>
-  readonly fallback: string
-}
-
-export interface ProductAliases {
-  readonly aliases: Readonly<Record<string, string>>
-}
-
-export interface Snapshot {
-  readonly files: ReadonlyMap<string, Uint8Array>
-  readonly symlinks: readonly string[]
-}
-
-/** Trusted compiler extension; never loaded from upstream plugin content. */
-export type ReleaseTransform = (
-  release: PluginRelease,
-  snapshot: Snapshot,
-  pluginName: string
-) => PluginRelease
-
-export interface SnapshotLoader {
-  load(repositoryUrl: string, commitSha: string, pluginSubdirectory: string): Promise<Snapshot>
-}
-
-export interface ResolvedSource {
-  readonly config: SourceConfig
-  readonly commitSha: string
-  readonly manifestText: string
-  readonly parsed: ParsedMarketplace
-  readonly pluginPins: readonly PluginSourcePin[]
-  readonly retrievedAt: string
-  readonly manifestDigest: string
-}
-
-export interface PluginSourcePin {
-  readonly pluginName: string
-  readonly repositoryUrl: string
-  readonly pluginSubdirectory: string
-  readonly resolvedCommitSha: string
-}
-
-export interface SyncInput extends ConsumerIndexOptions {
-  readonly sources: readonly SourceConfig[]
-  readonly categoryMap: CategoryMap
-  readonly productAliases: ProductAliases
-  readonly productCategories?: Record<string, string>
-  readonly productIconOverrides?: ProductIconOverrides
-  /** Where this catalog is published, so records carry absolute asset URLs. */
-  readonly publicationRepositoryUrl?: string
-  /** Directory that receives mirrored brand marks as the catalog is built. */
-  readonly iconAssetsDirectory?: string
-  readonly policy: CatalogPolicy
-  readonly mode?: 'live' | 'offline'
-  readonly fixtureRoot?: string
-  readonly sourceId?: string
-  readonly metadataOnly?: boolean
-  readonly dryRun?: boolean
-  readonly existingLock?: SourcesLock
-  readonly existingCatalog?: Catalog
-  readonly fromLock?: SourcesLock
-  readonly snapshotLoader?: SnapshotLoader
-  readonly resolveExternalRefs?: boolean
-  /** Rebuild even when source pins are unchanged (used for explicit format migrations). */
-  readonly forceRebuild?: boolean
-  readonly transformRelease?: ReleaseTransform
-}
-
-export interface SyncResult {
-  readonly changed: boolean
-  readonly dryRun: boolean
-  readonly sourceHeads: readonly { sourceId: string; commitSha: string }[]
-  readonly catalog?: Catalog
-  readonly lock?: SourcesLock
-  readonly artifacts?: GeneratedArtifacts
-  readonly changeReport: ChangeReport
-}
-
-export interface ChangeReport {
-  readonly schemaVersion: 1
-  readonly changedSources: readonly string[]
-  readonly addedPlugins: readonly string[]
-  readonly removedPlugins: readonly string[]
-  readonly changedPlugins: readonly string[]
-  readonly permissionSensitiveChanges: readonly string[]
-  readonly skippedPlugins: readonly SkippedPlugin[]
-  readonly contentResolution: 'complete' | 'complete-with-skips' | 'metadata-only'
-}
-
-export type PluginSkipReasonCode =
-  | 'GIT_SUBMODULE_UNSUPPORTED'
-  | 'PLUGIN_FILE_TOO_LARGE'
-  | 'PLUGIN_FILE_UNAVAILABLE'
-  | 'PLUGIN_MANIFEST_INVALID'
-  | 'PLUGIN_PATH_NOT_FOUND'
-  | 'PLUGIN_SCHEMA_INVALID'
-  | 'PLUGIN_SIZE_POLICY'
-  | 'PLUGIN_SOURCE_UNAVAILABLE'
-  | 'PLUGIN_TOO_LARGE'
-  | 'PLUGIN_TOO_MANY_FILES'
-  | 'SNAPSHOT_PATH_INVALID'
-  | 'SYMLINK_ESCAPE'
-
-export interface SkippedPlugin {
-  readonly sourceId: string
-  readonly pluginId: string
-  readonly pluginName: string
-  readonly reasonCode: PluginSkipReasonCode
-  readonly securityReason: string
-  readonly incompleteContent: true
-  readonly paths: readonly string[]
-}
-
-/**
- * Published artifacts by file name. The core six are always present; the
- * consumer shards (`catalog-index.v1.json`, `shelf-<category>.v1.json` and
- * `category-<category>.v1.json`) follow the configured categories.
- */
-export interface GeneratedArtifacts {
-  readonly [name: string]: string
-  readonly 'catalog.v1.json': string
-  readonly 'catalog-summary.v1.json': string
-  readonly 'sources.lock.json': string
-  readonly 'compatibility.v1.json': string
-  readonly 'categories.v1.json': string
-  readonly 'integrity.json': string
-}
-
-/** Result of checking a published consumer index against its catalog. */
-export interface ConsumerIndexVerification {
-  readonly hasConsumerIndex: boolean
-  readonly diagnostics: readonly LeadingDiagnostic[]
-  readonly counts?: ConsumerIndex['counts']
-  readonly topCount?: number
-  readonly products?: Readonly<Record<string, ConsumerProduct>>
-  readonly categories?: readonly ConsumerCategory[]
-  /** Shards the published integrity file set must carry for this index. */
-  readonly shards: readonly ShardArtifact[]
-}
-
-/** One consumer shard artifact and what it must contain. */
-export interface ShardArtifact {
-  readonly name: string
-  readonly kind: 'index' | 'shelf' | 'list'
-  readonly category?: string
-}
-
-/** Consumer index inputs: curated shelves and canonical-variant placement. */
-export interface ConsumerIndexOptions {
-  readonly leading?: Readonly<Record<string, readonly string[]>>
-  readonly topCount?: number
-  readonly productPreference?: ProductPreference
-  /**
-   * Where this catalog is published. When known, product records carry an
-   * absolute, immutable URL for their brand mark so no client composes one.
-   */
-  readonly publicationRepositoryUrl?: string
-  /**
-   * Base URL of the committed asset directory that browsers fetch directly.
-   *
-   * GitHub release assets answer a cross-origin `fetch` with no CORS header and
-   * redirect through a URL that cannot be cached, so a browser neither reads the
-   * index nor reuses an icon. The same files served from the repository are
-   * CORS-enabled, direct and cacheable.
-   */
-  readonly publicationAssetsBaseUrl?: string
-  /**
-   * Base URL of the content-addressed snapshot directory, one level below the
-   * asset branch. Catalog artifacts are addressed by catalog identity, so they
-   * live in `catalogs/<catalogId>/` while digest-addressed brand marks sit at
-   * the branch root.
-   */
-  readonly publicationCatalogsBaseUrl?: string
-  /**
-   * Whether curated-name drift is published in the consumer index. An offline
-   * build replays fixtures rather than the upstream catalogs, so its curation
-   * findings are noise and are omitted by default.
-   */
-  readonly curationDiagnostics?: boolean
-}
-
-const DEFAULT_POLICY: CatalogPolicy = {
-  allowedRepositoryProtocols: ['https:'],
-  allowedRepositoryHosts: ['github.com', 'www.github.com'],
-  maxFilesPerPlugin: 4096,
-  maxBytesPerPlugin: 50 * 1024 * 1024,
-  maxFileBytes: 5 * 1024 * 1024,
-  maxMarketplacePlugins: 4096,
-  denyExecutableLifecycleScripts: true,
-  publishRequiresCompleteContent: false,
-  sensitiveCapabilityTypes: [
-    'mcp-server',
-    'connector',
-    'hook',
-    'browser',
-    'scheduled-task',
-    'executable',
-  ],
-}
-
-export function canonicalJson(value: unknown): string {
-  if (value === null || typeof value !== 'object') return JSON.stringify(value)
-  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`
-  const object = value as Record<string, unknown>
-  return `{${Object.keys(object)
-    .toSorted()
-    .map((key) => `${JSON.stringify(key)}:${canonicalJson(object[key])}`)
-    .join(',')}}`
-}
-
-export function digest(value: unknown): string {
-  return `sha256:${createHash('sha256').update(canonicalJson(value)).digest('hex')}`
-}
-
-export function stablePluginId(sourceId: string, upstreamName: string): string {
-  return `plugin:${slug(sourceId)}:${slug(upstreamName)}`
-}
-
-export function stableReleaseId(
-  repositoryUrl: string,
-  subdirectory: string,
-  commitSha: string,
-  contentDigest: string
-): string {
-  return `release:${digest({ repositoryUrl, subdirectory, commitSha, contentDigest }).slice('sha256:'.length)}`
-}
-
-export function normalizeCategory(value: string, map: CategoryMap): string {
-  const key = value.trim().toLocaleLowerCase()
-  return map.aliases[key] ?? (slug(key) || map.fallback)
-}
-
-export function productGroupingKey(name: string, aliases: ProductAliases): string {
-  const key = name.trim().toLocaleLowerCase()
-  return aliases.aliases[key] ?? slug(key)
-}
-
-export async function synchronize(input: SyncInput): Promise<SyncResult> {
-  const mode = input.mode ?? 'live'
-  const configs = input.sources.filter(
-    (source) => !input.sourceId || source.sourceId === input.sourceId
-  )
-  if (configs.length === 0) throw new Error(`SOURCE_NOT_FOUND: ${input.sourceId ?? 'none'}`)
-  const lockToUse = input.fromLock ?? input.existingLock
-  const resolved = await mapWithConcurrency(configs, 4, (config) =>
-    resolveSource(config, mode, input.fixtureRoot, lockToUse, input.fromLock !== undefined)
-  )
-  const sourceHeads = resolved.map(({ config, commitSha }) => ({
-    sourceId: config.sourceId,
-    commitSha,
-  }))
-  const unchanged =
-    input.fromLock === undefined &&
-    input.forceRebuild !== true &&
-    input.existingLock !== undefined &&
-    resolved.length === input.existingLock.sources.length &&
-    resolved.every((source) => {
-      const previous = input.existingLock?.sources.find(
-        (entry) => entry.sourceId === source.config.sourceId
-      )
-      if (!previous) return false
-      return (
-        previous.resolvedCommitSha === source.commitSha &&
-        previous.sourceManifestDigest === source.manifestDigest &&
-        digest(previous.pluginPins) === digest(source.pluginPins)
-      )
-    })
-  if (unchanged) {
-    return {
-      changed: false,
-      dryRun: input.dryRun ?? false,
-      sourceHeads,
-      changeReport: {
-        schemaVersion: 1,
-        changedSources: [],
-        addedPlugins: [],
-        removedPlugins: [],
-        changedPlugins: [],
-        permissionSensitiveChanges: [],
-        skippedPlugins: [],
-        contentResolution: input.metadataOnly ? 'metadata-only' : 'complete',
-      },
-    }
-  }
-
-  const buildResult = await buildCatalogInternal({
-    resolvedSources: resolved,
-    categoryMap: input.categoryMap,
-    ...(input.productCategories ? { productCategories: input.productCategories } : {}),
-    ...(input.leading ? { leading: input.leading } : {}),
-    ...(input.productIconOverrides ? { productIconOverrides: input.productIconOverrides } : {}),
-    ...(input.iconAssetsDirectory ? { iconAssetsDirectory: input.iconAssetsDirectory } : {}),
-    productAliases: input.productAliases,
-    policy: input.policy,
-    metadataOnly: input.metadataOnly ?? false,
-    snapshotLoader:
-      input.snapshotLoader ??
-      (mode === 'offline'
-        ? new FixtureSnapshotLoader(input.fixtureRoot ?? 'fixtures', configs)
-        : new NetworkSnapshotLoader(input.policy)),
-    resolveExternalRefs: mode === 'live',
-    ...(input.transformRelease ? { transformRelease: input.transformRelease } : {}),
-  })
-  const catalog = buildResult.catalog
-  const lock = createSourcesLock(resolved)
-  const artifacts = createArtifacts(orderLeadingPlugins(catalog, input.leading), lock, {
-    ...(input.leading ? { leading: input.leading } : {}),
-    ...(input.topCount !== undefined ? { topCount: input.topCount } : {}),
-    ...(input.productPreference ? { productPreference: input.productPreference } : {}),
-    ...(input.publicationRepositoryUrl
-      ? { publicationRepositoryUrl: input.publicationRepositoryUrl }
-      : {}),
-    ...(input.publicationAssetsBaseUrl
-      ? { publicationAssetsBaseUrl: input.publicationAssetsBaseUrl }
-      : {}),
-    ...(input.publicationCatalogsBaseUrl
-      ? { publicationCatalogsBaseUrl: input.publicationCatalogsBaseUrl }
-      : {}),
-    curationDiagnostics: (input.mode ?? 'live') !== 'offline',
-  })
-  verifyArtifacts(artifacts)
-  const report = createChangeReport(
-    catalog,
-    lock,
-    input.existingLock,
-    input.existingCatalog,
-    buildResult.skippedPlugins
-  )
-  if (input.policy.publishRequiresCompleteContent && input.metadataOnly) {
-    throw new Error('CATALOG_CONTENT_INCOMPLETE: publication requires complete content')
-  }
-  return {
-    changed: true,
-    dryRun: input.dryRun ?? false,
-    sourceHeads,
-    catalog,
-    lock,
-    artifacts,
-    changeReport: report,
-  }
-}
-
-export async function buildCatalog(input: {
-  readonly resolvedSources: readonly ResolvedSource[]
-  readonly categoryMap: CategoryMap
-  readonly productAliases: ProductAliases
-  readonly productCategories?: Record<string, string>
-  readonly leading?: Record<string, readonly string[]>
-  readonly productIconOverrides?: ProductIconOverrides
-  readonly iconAssetsDirectory?: string
-  readonly policy?: CatalogPolicy
-  readonly metadataOnly?: boolean
-  readonly snapshotLoader: SnapshotLoader
-  readonly resolveExternalRefs?: boolean
-  readonly transformRelease?: ReleaseTransform
-}): Promise<Catalog> {
-  return (
-    await buildCatalogInternal({
-      resolvedSources: input.resolvedSources,
-      categoryMap: input.categoryMap,
-      productAliases: input.productAliases,
-      policy: input.policy ?? DEFAULT_POLICY,
-      metadataOnly: input.metadataOnly ?? false,
-      snapshotLoader: input.snapshotLoader,
-      resolveExternalRefs: input.resolveExternalRefs ?? false,
-      ...(input.transformRelease ? { transformRelease: input.transformRelease } : {}),
-      ...(input.productCategories ? { productCategories: input.productCategories } : {}),
-      ...(input.leading ? { leading: input.leading } : {}),
-      ...(input.productIconOverrides ? { productIconOverrides: input.productIconOverrides } : {}),
-      ...(input.iconAssetsDirectory ? { iconAssetsDirectory: input.iconAssetsDirectory } : {}),
-    })
-  ).catalog
-}
-
-interface BuildCatalogInput {
-  readonly resolvedSources: readonly ResolvedSource[]
-  readonly categoryMap: CategoryMap
-  readonly productAliases: ProductAliases
-  readonly productCategories?: Record<string, string>
-  readonly leading?: Record<string, readonly string[]>
-  readonly productIconOverrides?: ProductIconOverrides
-  readonly iconAssetsDirectory?: string
-  readonly policy?: CatalogPolicy
-  readonly metadataOnly?: boolean
-  readonly snapshotLoader: SnapshotLoader
-  readonly resolveExternalRefs?: boolean
-  readonly transformRelease?: ReleaseTransform
-}
-
-interface BuildCatalogResult {
-  readonly catalog: Catalog
-  readonly skippedPlugins: readonly SkippedPlugin[]
-}
-
-async function buildCatalogInternal(input: BuildCatalogInput): Promise<BuildCatalogResult> {
-  const policy = input.policy ?? DEFAULT_POLICY
-  for (const source of input.resolvedSources) {
-    assertRepositoryAllowed(source.config.repositoryUrl, policy)
-    for (const entry of source.parsed.entries) {
-      if (entry.source.kind === 'git') assertRepositoryAllowed(entry.source.repositoryUrl, policy)
-    }
-  }
-  const sourceRecords: CatalogSource[] = input.resolvedSources
-    .map(({ config, commitSha, retrievedAt, manifestDigest }) => ({
-      sourceId: config.sourceId,
-      displayName: config.displayName,
-      repositoryUrl: canonicalRepositoryUrl(config.repositoryUrl),
-      marketplaceDialect: config.marketplaceDialect,
-      manifestPath: config.manifestPath,
-      defaultBranch: config.defaultBranch,
-      resolvedCommitSha: commitSha,
-      retrievalTimestamp: retrievedAt,
-      trustClassification: config.trustClassification,
-      sourceManifestDigest: manifestDigest,
-      synchronizationStatus: 'synchronized' as const,
-    }))
-    .toSorted((left, right) => left.sourceId.localeCompare(right.sourceId))
-  let plugins: Plugin[] = []
-  let skippedPlugins: SkippedPlugin[] = []
-  for (const source of input.resolvedSources) {
-    if (source.parsed.entries.length > policy.maxMarketplacePlugins)
-      throw new Error('MARKETPLACE_TOO_MANY_PLUGINS')
-    const normalized = await mapWithConcurrency(source.parsed.entries, 8, async (entry) => {
-      try {
-        const plugin = await normalizePlugin({
-          source,
-          entry,
-          categoryMap: input.categoryMap,
-          ...(input.productCategories ? { productCategories: input.productCategories } : {}),
-          productAliases: input.productAliases,
-          ...(input.productIconOverrides
-            ? { productIconOverrides: input.productIconOverrides }
-            : {}),
-          ...(input.iconAssetsDirectory ? { iconAssetsDirectory: input.iconAssetsDirectory } : {}),
-          policy,
-          metadataOnly: input.metadataOnly ?? false,
-          snapshotLoader: input.snapshotLoader,
-          resolveExternalRefs: input.resolveExternalRefs ?? true,
-          ...(input.transformRelease ? { transformRelease: input.transformRelease } : {}),
-        })
-        try {
-          return { plugin: PluginSchema.parse(plugin) }
-        } catch {
-          throw new PluginSafetyError('PLUGIN_SCHEMA_INVALID', [])
-        }
-      } catch (error) {
-        const skipped = createSkippedPlugin(source, entry, error)
-        if (!skipped) throw error
-        return { skipped }
-      }
-    })
-    const sourcePlugins: Plugin[] = []
-    const sourceSkipped: SkippedPlugin[] = []
-    for (const result of normalized) {
-      if (result.plugin) sourcePlugins.push(result.plugin)
-      if (result.skipped) sourceSkipped.push(result.skipped)
-    }
-    const weatherSkips = sourceSkipped.filter((skipped) =>
-      UPSTREAM_WEATHER_SKIP_CODES.has(skipped.reasonCode)
-    )
-    if (source.parsed.entries.length > 0 && weatherSkips.length === source.parsed.entries.length)
-      throw new PluginSafetyError('PLUGIN_SOURCE_UNAVAILABLE', [
-        canonicalRepositoryUrl(source.config.repositoryUrl),
-      ])
-    for (const plugin of sourcePlugins) plugins.push(plugin)
-    for (const skipped of sourceSkipped) skippedPlugins.push(skipped)
-  }
-  plugins = plugins.toSorted((left, right) => left.pluginId.localeCompare(right.pluginId))
-  skippedPlugins = skippedPlugins.toSorted(
-    (left, right) =>
-      left.pluginId.localeCompare(right.pluginId) ||
-      left.reasonCode.localeCompare(right.reasonCode) ||
-      left.paths.join('\0').localeCompare(right.paths.join('\0'))
-  )
-  const body = {
-    schemaVersion: 1 as const,
-    generatedAt:
-      sourceRecords
-        .map((s) => s.retrievalTimestamp)
-        .toSorted()
-        .at(-1) ?? new Date(0).toISOString(),
-    sources: sourceRecords,
-    plugins,
-  }
-  return {
-    catalog: CatalogSchema.parse({
-      ...body,
-      catalogId: `catalog:${digest(body).slice('sha256:'.length)}`,
-    }),
-    skippedPlugins,
-  }
-}
-
-class PluginSafetyError extends Error {
-  constructor(
-    readonly reasonCode: PluginSkipReasonCode,
-    readonly paths: readonly string[]
-  ) {
-    super(`${reasonCode}${paths.length > 0 ? `: ${paths.join(',')}` : ''}`)
-    this.name = 'PluginSafetyError'
-  }
-}
-
-const pluginSkipReasons: Readonly<Record<PluginSkipReasonCode, string>> = {
-  GIT_SUBMODULE_UNSUPPORTED:
-    'The plugin contains a Git submodule, so the catalog excludes it rather than traversing an unpinned repository boundary.',
-  PLUGIN_FILE_TOO_LARGE:
-    'The plugin contains a file over the configured size limit, so the catalog excludes the plugin before publication.',
-  PLUGIN_FILE_UNAVAILABLE:
-    'A plugin file could not be fetched from upstream after retries, so the catalog excludes the plugin rather than publishing partial content.',
-  PLUGIN_MANIFEST_INVALID:
-    'The plugin manifest is malformed, so the catalog excludes the plugin before consuming its metadata.',
-  PLUGIN_PATH_NOT_FOUND:
-    'The declared plugin path does not exist at the pinned commit, so the catalog excludes the plugin.',
-  PLUGIN_SCHEMA_INVALID:
-    'The normalized plugin record exceeds the published catalog schema, so the catalog excludes it before publication.',
-  PLUGIN_SIZE_POLICY:
-    'The plugin exceeds the configured size policy, so the catalog excludes it before publication.',
-  PLUGIN_SOURCE_UNAVAILABLE:
-    'The plugin repository tree could not be fetched from upstream after retries, so the catalog excludes the plugin rather than publishing partial content.',
-  PLUGIN_TOO_LARGE:
-    'The plugin exceeds the configured aggregate size limit, so the catalog excludes it before publication.',
-  PLUGIN_TOO_MANY_FILES:
-    'The plugin exceeds the configured file-count limit, so the catalog excludes it before publication.',
-  SNAPSHOT_PATH_INVALID:
-    'The plugin snapshot contains an unsafe path, so the catalog excludes it rather than allowing repository escape.',
-  SYMLINK_ESCAPE:
-    'The plugin snapshot contains symlinks; symlinks are never followed, so the catalog excludes the plugin.',
-}
-
-function createSkippedPlugin(
-  source: ResolvedSource,
-  entry: MarketplacePluginEntry,
-  error: unknown
-): SkippedPlugin | undefined {
-  const parsed =
-    error instanceof PluginSafetyError
-      ? { reasonCode: error.reasonCode, paths: error.paths }
-      : parsePluginSafetyError(error)
-  if (!parsed) return undefined
-  return {
-    sourceId: source.config.sourceId,
-    pluginId: stablePluginId(source.config.sourceId, entry.name),
-    pluginName: entry.name,
-    reasonCode: parsed.reasonCode,
-    securityReason: pluginSkipReasons[parsed.reasonCode],
-    incompleteContent: true,
-    paths: [...new Set(parsed.paths)].toSorted(),
-  }
-}
-
-function parsePluginSafetyError(
-  error: unknown
-): { reasonCode: PluginSkipReasonCode; paths: readonly string[] } | undefined {
-  const message = error instanceof Error ? error.message : String(error)
-  const match = /^([A-Z_]+)(?::\s?(.*))?$/.exec(message)
-  if (!match) return undefined
-  const reasonCode = match[1] as PluginSkipReasonCode
-  if (!(reasonCode in pluginSkipReasons)) return undefined
-  return {
-    reasonCode,
-    paths: match[2]
-      ? match[2]
-          .split(',')
-          .map((path) => path.trim())
-          .filter(Boolean)
-      : [],
-  }
-}
-
-async function normalizePlugin(input: {
-  readonly source: ResolvedSource
-  readonly entry: MarketplacePluginEntry
-  readonly categoryMap: CategoryMap
-  readonly productCategories?: Record<string, string>
-  readonly productAliases: ProductAliases
-  readonly productIconOverrides?: ProductIconOverrides
-  readonly iconAssetsDirectory?: string
-  readonly policy: CatalogPolicy
-  readonly metadataOnly: boolean
-  readonly snapshotLoader: SnapshotLoader
-  readonly resolveExternalRefs: boolean
-  readonly transformRelease?: ReleaseTransform
-}): Promise<Plugin> {
-  const { source, entry, policy } = input
-  const resolved = await resolvePluginSource(
-    entry.name,
-    entry.source,
-    source,
-    input.resolveExternalRefs
-  )
-  const snapshot = input.metadataOnly
-    ? { files: new Map<string, Uint8Array>(), symlinks: [] }
-    : await input.snapshotLoader.load(
-        resolved.repositoryUrl,
-        resolved.commitSha,
-        resolved.subdirectory
-      )
-  if (snapshot.symlinks.length > 0)
-    throw new PluginSafetyError('SYMLINK_ESCAPE', [...snapshot.symlinks].toSorted())
-  validateSnapshot(snapshot, policy, entry.name)
-  const contentDigest = input.metadataOnly
-    ? digest({
-        repositoryUrl: resolved.repositoryUrl,
-        subdirectory: resolved.subdirectory,
-        commitSha: resolved.commitSha,
-        entryDigest: entry.entryDigest,
-      })
-    : bytesDigest(snapshot.files)
-  const pluginManifest = findPluginManifest(snapshot, input.transformRelease !== undefined)
-  const manifestDigest = pluginManifest ? digest(pluginManifest.metadata) : entry.entryDigest
-  const capabilities = classifyCapabilities(snapshot.files, pluginManifest?.metadata)
-  const iconOverride = iconOverrideFor(
-    input.productIconOverrides,
-    productGroupingKey(entry.name, input.productAliases)
-  )
-  const contentIcon = resolveContentIcon(snapshot, iconOverride, input.metadataOnly ?? false)
-  const favicon =
-    contentIcon === undefined
-      ? await resolveFavicon({
-          entry,
-          iconOverride,
-          metadataOnly: input.metadataOnly ?? false,
-          live: input.resolveExternalRefs === true,
-        })
-      : undefined
-  // Stage the mark while its bytes are in hand. Publication then needs no
-  // re-fetch, and a site icon cannot drift between resolution and release.
-  if (input.iconAssetsDirectory) {
-    const staged = contentIcon
-      ? snapshot.files.get(contentIcon.kind === 'content' ? contentIcon.path : '')
-      : favicon?.bytes
-    if (staged)
-      await stageIconBytes(
-        input.iconAssetsDirectory,
-        iconAssetName(
-          contentIcon ? contentIcon.digest : favicon!.digest,
-          contentIcon ? contentIcon.contentType : favicon!.contentType
-        ),
-        staged
-      )
-  }
-  const releaseId = stableReleaseId(
-    resolved.repositoryUrl,
-    resolved.subdirectory,
-    resolved.commitSha,
-    contentDigest
-  )
-  const originalRelease = createRelease({
-    source,
-    entry,
-    resolved,
-    contentDigest,
-    manifestDigest,
-    capabilities,
-    snapshot,
-    ...(pluginManifest ? { pluginManifest } : {}),
-    releaseId,
-    ...(contentIcon ? { contentIcon } : {}),
-    ...(favicon ? { favicon } : {}),
-    metadataOnly: input.metadataOnly,
-  })
-  const release =
-    input.transformRelease && !input.metadataOnly
-      ? input.transformRelease(originalRelease, snapshot, entry.name)
-      : originalRelease
-  const compatibility = createCompatibility(source.config.marketplaceDialect, capabilities, policy)
-  const security = createSecurity(capabilities, policy, input.metadataOnly)
-  const normalizedCategories = entry.categories.map((category) =>
-    normalizeCategory(category, input.categoryMap)
-  )
-  const productCategory = input.productCategories?.[entry.name]
-  const categories = [
-    ...new Set(
-      (productCategory
-        ? [productCategory, ...normalizedCategories.filter((category) => category !== 'other')]
-        : normalizedCategories.length > 0
-          ? normalizedCategories
-          : [input.categoryMap.fallback]
-      ).filter(Boolean)
-    ),
-  ].toSorted()
-  // The name a list renders: marketplace manifests are inconsistent (`Gmail`
-  // beside `zapier` beside `aws-agents-for-devsecops`), so the catalog
-  // publishes the written form once and every consumer shows the same thing.
-  const displayName = normalizeDisplayName(
-    entry.displayName ?? pluginManifest?.displayName ?? entry.name
-  )
-  const authors =
-    entry.authors.length > 0
-      ? [...entry.authors]
-      : source.parsed.owner.length > 0
-        ? [...source.parsed.owner]
-        : ['Unknown']
-  const keywords = [...new Set([...entry.keywords, ...entry.name.split(/[-_\s]+/g), ...categories])]
-    .filter(Boolean)
-    .toSorted()
-  const provenance: PluginProvenance = {
-    sourceId: source.config.sourceId,
-    repositoryUrl: canonicalRepositoryUrl(source.config.repositoryUrl),
-    manifestPath: source.config.manifestPath,
-    pluginSubdirectory: resolved.subdirectory || '.',
-    resolvedCommitSha: resolved.commitSha,
-    sourceManifestDigest: source.manifestDigest,
-    upstreamEntryDigest: entry.entryDigest,
-  }
-  return {
-    pluginId: stablePluginId(source.config.sourceId, entry.name),
-    displayName,
-    description: entry.description || pluginManifest?.description || '',
-    productGroupingKey: productGroupingKey(entry.name, input.productAliases),
-    categories,
-    keywords,
-    authors,
-    ...(entry.homepage ? { homepage: entry.homepage } : {}),
-    icons: entry.icons.length > 0 ? [...entry.icons].toSorted() : (pluginManifest?.icons ?? []),
-    sourceId: source.config.sourceId,
-    upstreamPluginName: entry.name,
-    currentReleaseId: releaseId,
-    availableReleases: [release],
-    capabilitySummary: capabilitySummary(capabilities),
-    harnessCompatibility: compatibility,
-    license: findLicense(entry, pluginManifest?.metadata),
-    provenance,
-    securityClassification: security,
-  }
-}
-
-interface CreateReleaseInput {
-  readonly source: ResolvedSource
-  readonly entry: MarketplacePluginEntry
-  readonly resolved: ResolvedPluginSource
-  readonly contentDigest: string
-  readonly manifestDigest: string
-  readonly capabilities: readonly Capability[]
-  readonly snapshot: Snapshot
-  readonly pluginManifest?: PluginManifest
-  readonly releaseId: string
-  readonly contentIcon?: PluginRelease['icon'] | undefined
-  readonly favicon?: SiteIcon | undefined
-  readonly metadataOnly: boolean
-}
-
-function createRelease(input: CreateReleaseInput): PluginRelease {
-  const requiredCredentials = new Set<string>()
-  const auth = input.entry.policy.authentication
-  if (typeof auth === 'string' && auth !== 'NONE' && auth !== 'DISABLED')
-    requiredCredentials.add('authentication')
-  for (const value of arrayValue(input.entry.raw.requiredCredentials))
-    if (typeof value === 'string') requiredCredentials.add(value)
-  const requiredConnectors = [
-    ...new Set(arrayValue(input.entry.raw.connectors).filter(isString)),
-  ].toSorted()
-  const permissionSensitiveChanges = input.capabilities
-    .filter((capability) => capability.securityImpact === 'sensitive')
-    .map((capability) => capability.type)
-    .toSorted()
-  const metadata: Record<string, unknown> = {
-    catalogContract: CATALOG_CONTRACT_VERSION,
-    marketplaceEntry: input.entry.raw,
-    ...(input.pluginManifest ? { pluginManifest: input.pluginManifest.metadata } : {}),
-    sourceDialect: input.source.config.marketplaceDialect,
-  }
-  const version = input.pluginManifest?.version ?? stringValue(input.entry.raw.version)
-  return {
-    releaseId: input.releaseId,
-    ...(version ? { upstreamVersion: version } : {}),
-    resolvedRepositoryUrl: input.resolved.repositoryUrl,
-    resolvedCommitSha: input.resolved.commitSha,
-    pluginSubdirectory: input.resolved.subdirectory || '.',
-    canonicalContentDigest: input.contentDigest,
-    manifestDigest: input.manifestDigest,
-    contentResolution: input.metadataOnly ? 'metadata-only' : 'complete',
-    releaseMetadata: metadata,
-    capabilities: [...input.capabilities].toSorted(
-      (left, right) => left.type.localeCompare(right.type) || left.name.localeCompare(right.name)
-    ),
-    requiredConnectors,
-    requiredCredentials: [...requiredCredentials].toSorted(),
-    permissionSensitiveChanges: [...new Set(permissionSensitiveChanges)],
-    fileIndex: [...input.snapshot.files.keys()].toSorted(),
-    publicationTimestamp: input.source.retrievedAt,
-    ...assembleIcon(input),
-  }
-}
-
-/**
- * Resolves the product site's icon, for a plugin whose content ships no mark.
- *
- * Only a live build with complete content attempts this: a metadata-only or
- * offline run must not reach out to vendor sites, and neither may a product the
- * curator has already decided about.
- */
-async function resolveFavicon(input: {
-  readonly entry: MarketplacePluginEntry
-  readonly iconOverride?: IconOverride | undefined
-  readonly metadataOnly: boolean
-  readonly live: boolean
-}): Promise<SiteIcon | undefined> {
-  if (!input.live || input.metadataOnly) return undefined
-  if (input.iconOverride?.forced === null || input.iconOverride?.forced) return undefined
-  const homepage = input.iconOverride?.site ?? input.entry.homepage
-  if (!isVendorHomepage(homepage)) return undefined
-  // Bound both fetches: a vendor site that never answers must not stall a
-  // catalogue build. A timeout simply leaves the product on its monogram.
-  const signal = AbortSignal.timeout(SITE_FETCH_TIMEOUT_MS)
-  const resolved = await resolveSiteIcon(homepage!, createSiteIconFetcher(signal))
-  return 'contentType' in resolved ? resolved : undefined
-}
-
-/**
- * Picks and vets the brand mark for a release.
- *
- * A file in the plugin's own content is preferred, because it is the mark the
- * vendor ships with the plugin. When the content has none, a live build falls
- * back to the declared homepage's site icon: many plugins are a thin wrapper
- * over a vendor API and point at the vendor's site rather than shipping a logo.
- * Whatever the source, an icon that fails inspection is absent rather than
- * advertised: the catalog never publishes content it would refuse to mirror.
- */
-function resolveContentIcon(
-  snapshot: Snapshot,
-  iconOverride: IconOverride | undefined,
-  metadataOnly: boolean
-): PluginRelease['icon'] | undefined {
-  if (metadataOnly || snapshot.files.size === 0) return undefined
-  // A curator override wins over every rule, including "publish no icon".
-  if (iconOverride?.forced === null) return undefined
-  const files = [...snapshot.files.keys()].toSorted()
-  const forced = iconOverride?.forced
-  if (forced && !files.includes(forced)) return undefined
-  const path = forced ?? selectIconPath(files)
-  if (!path) return undefined
-  const bytes = snapshot.files.get(path)
-  if (!bytes) return undefined
-  const inspected = inspectIconBytes(bytes)
-  if (!('contentType' in inspected)) return undefined
-  return {
-    kind: 'content',
-    path,
-    contentType: inspected.contentType,
-    digest: byteDigest(bytes),
-    bytes: bytes.byteLength,
-  }
-}
-
-type IconOverride = ReturnType<typeof iconOverrideFor>
-
-/** Assembles the release icon from whichever source produced one. */
-function assembleIcon(
-  input: Pick<CreateReleaseInput, 'contentIcon' | 'favicon'>
-): { icon: NonNullable<PluginRelease['icon']> } | Record<string, never> {
-  if (input.contentIcon) return { icon: input.contentIcon }
-  if (input.favicon)
-    return {
-      icon: {
-        kind: 'favicon',
-        url: input.favicon.url,
-        homepage: input.favicon.homepage,
-        contentType: input.favicon.contentType,
-        digest: input.favicon.digest,
-        bytes: input.favicon.bytes.byteLength,
-      },
-    }
-  return {}
-}
-
-/** SHA-256 of a single byte buffer, in the catalog's digest format. */
-export function byteDigest(bytes: Uint8Array): string {
-  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`
-}
-
-async function resolvePluginSource(
-  pluginName: string,
-  spec: PluginSourceSpec,
-  source: ResolvedSource,
-  resolveExternalRefs: boolean
-): Promise<ResolvedPluginSource> {
-  if (spec.kind === 'local')
-    return {
-      repositoryUrl: canonicalRepositoryUrl(source.config.repositoryUrl),
-      subdirectory: spec.path,
-      commitSha: source.commitSha,
-    }
-  const canonicalUrl = canonicalRepositoryUrl(spec.repositoryUrl)
-  const pin = source.pluginPins.find(
-    (candidate) =>
-      candidate.pluginName === pluginName &&
-      candidate.repositoryUrl === canonicalUrl &&
-      candidate.pluginSubdirectory === spec.subdirectory
-  )
-  const commitSha =
-    pin?.resolvedCommitSha ??
-    spec.sha ??
-    (resolveExternalRefs
-      ? await resolveGitRef(
-          spec.repositoryUrl,
-          spec.ref?.startsWith('refs/') ? spec.ref : `refs/heads/${spec.ref ?? 'main'}`
-        )
-      : source.commitSha)
-  return {
-    repositoryUrl: canonicalUrl,
-    subdirectory: pin?.pluginSubdirectory ?? spec.subdirectory,
-    commitSha,
-  }
-}
-
-interface ResolvedPluginSource {
-  readonly repositoryUrl: string
-  readonly subdirectory: string
-  readonly commitSha: string
-}
-
-function validateSnapshot(snapshot: Snapshot, policy: CatalogPolicy, pluginName: string): void {
-  if (snapshot.files.size > policy.maxFilesPerPlugin)
-    throw new PluginSafetyError('PLUGIN_TOO_MANY_FILES', [pluginName])
-  let total = 0
-  for (const [path, bytes] of snapshot.files) {
-    try {
-      safeRelativePath(path, 'SNAPSHOT_PATH_INVALID')
-    } catch {
-      throw new PluginSafetyError('SNAPSHOT_PATH_INVALID', [path])
-    }
-    if (bytes.byteLength > policy.maxFileBytes)
-      throw new PluginSafetyError('PLUGIN_FILE_TOO_LARGE', [path])
-    total += bytes.byteLength
-  }
-  if (total > policy.maxBytesPerPlugin)
-    throw new PluginSafetyError('PLUGIN_TOO_LARGE', [pluginName])
-}
-
-function assertRepositoryAllowed(repositoryUrl: string, policy: CatalogPolicy): void {
-  const parsed = new URL(canonicalRepositoryUrl(repositoryUrl))
-  if (!policy.allowedRepositoryProtocols.includes(parsed.protocol))
-    throw new Error(`GIT_PROTOCOL_POLICY: ${parsed.protocol}`)
-  if (!policy.allowedRepositoryHosts.includes(parsed.hostname.toLowerCase()))
-    throw new Error(`GIT_HOST_POLICY: ${parsed.hostname}`)
-}
-
-interface PluginManifest {
-  readonly metadata: Record<string, unknown>
-  readonly displayName?: string | undefined
-  readonly description?: string | undefined
-  readonly version?: string | undefined
-  readonly icons: string[]
-}
-
-function findPluginManifest(snapshot: Snapshot, preferRoot = false): PluginManifest | undefined {
-  const candidates = [...snapshot.files.keys()]
-    .filter((path) => {
-      const lower = path.toLocaleLowerCase()
-      return lower === 'plugin.json' || lower.endsWith('/plugin.json') || lower === 'package.json'
-    })
-    .toSorted(
-      (left, right) => manifestRank(left) - manifestRank(right) || left.localeCompare(right)
-    )
-  const path = preferRoot && snapshot.files.has('plugin.json') ? 'plugin.json' : candidates[0]
-  if (!path) return undefined
-  try {
-    const bytes = snapshot.files.get(path)
-    if (!bytes) return undefined
-    const metadata = parseJsonDocument(new TextDecoder().decode(bytes)) as Record<string, unknown>
-    return {
-      metadata,
-      ...((stringValue(metadata.displayName) ?? stringValue(metadata.name))
-        ? { displayName: stringValue(metadata.displayName) ?? stringValue(metadata.name) }
-        : {}),
-      ...(stringValue(metadata.description)
-        ? { description: stringValue(metadata.description) }
-        : {}),
-      ...(stringValue(metadata.version) ? { version: stringValue(metadata.version) } : {}),
-      icons: [metadata.icon, ...(Array.isArray(metadata.icons) ? metadata.icons : [])]
-        .filter(isString)
-        .toSorted(),
-    }
-  } catch {
-    throw new PluginSafetyError('PLUGIN_MANIFEST_INVALID', [path])
-  }
-}
-
-function manifestRank(path: string): number {
-  const lower = path.toLocaleLowerCase()
-  if (lower.endsWith('/.claude-plugin/plugin.json')) return 0
-  if (lower.endsWith('/.cursor-plugin/plugin.json')) return 1
-  if (lower.endsWith('/.agents/plugin.json')) return 2
-  return lower === 'plugin.json' ? 3 : 4
-}
-
-export function classifyCapabilities(
-  files: ReadonlyMap<string, Uint8Array>,
-  metadata?: Record<string, unknown>
-): Capability[] {
-  const groups = new Map<string, string[]>()
-  const add = (type: Capability['type'], path: string) =>
-    groups.set(type, [...(groups.get(type) ?? []), path])
-  for (const path of files.keys()) {
-    const lower = path.toLocaleLowerCase()
-    const file = basename(lower)
-    if (file === 'skill.md' || lower.includes('/skills/')) add('skill', path)
-    if (file === '.mcp.json' || file === 'mcp.json' || lower.includes('/mcp-servers/'))
-      add('mcp-server', path)
-    if (lower.includes('/commands/') || lower.startsWith('commands/')) add('command', path)
-    if (lower.includes('/agents/') || lower.startsWith('agents/') || lower.includes('/subagents/'))
-      add('agent', path)
-    if (lower.includes('/hooks/') || lower.startsWith('hooks/') || file === 'hooks.json')
-      add('hook', path)
-    if (
-      lower.includes('/rules/') ||
-      lower.startsWith('rules/') ||
-      file === 'agents.md' ||
-      file === 'claude.md' ||
-      lower.includes('.cursor/rules/')
-    )
-      add('rule', path)
-    if (lower.includes('browser') || lower.includes('playwright') || lower.includes('chrome'))
-      add('browser', path)
-    if (lower.includes('/schedule') || lower.includes('/cron') || file.includes('schedule'))
-      add('scheduled-task', path)
-    if (lower.includes('/ui/') || lower.startsWith('ui/') || lower.includes('/components/'))
-      add('ui-component', path)
-    if (
-      lower.startsWith('bin/') ||
-      lower.startsWith('scripts/') ||
-      /\.(sh|bash|py|exe|bin)$/.test(file)
-    )
-      add('executable', path)
-  }
-  if (metadata && (metadata.mcpServers !== undefined || metadata.mcp !== undefined))
-    add('mcp-server', 'plugin-manifest')
-  if (metadata && (metadata.hooks !== undefined || metadata.hook !== undefined))
-    add('hook', 'plugin-manifest')
-  if (groups.size === 0) groups.set('unknown', ['plugin-root'])
-  return [...groups.entries()].map(([type, paths]) => ({
-    type: type as Capability['type'],
-    name: type,
-    paths: [...new Set(paths)].toSorted(),
-    metadata: {},
-    securityImpact: [
-      'mcp-server',
-      'connector',
-      'hook',
-      'browser',
-      'scheduled-task',
-      'executable',
-    ].includes(type)
-      ? 'sensitive'
-      : 'none',
-  }))
-}
-
-function capabilitySummary(
-  capabilities: readonly Capability[]
-): Record<Capability['type'], number> {
-  const summary = {} as Record<Capability['type'], number>
-  for (const capability of capabilities) summary[capability.type] = capability.paths.length
-  return summary
-}
-
-export function createCompatibility(
-  dialect: MarketplaceDialectName,
-  capabilities: readonly Capability[],
-  policy: CatalogPolicy = DEFAULT_POLICY
-): Record<Harness, HarnessCompatibility> {
-  const types = [...new Set(capabilities.map((capability) => capability.type))].toSorted()
-  const sensitive = types.filter((type) => policy.sensitiveCapabilityTypes.includes(type))
-  const make = (
-    status: HarnessCompatibility['status'],
-    reasons: string[]
-  ): HarnessCompatibility => ({
-    status,
-    reasons: [...new Set(reasons)].toSorted(),
-    responsibleCapabilities: types,
-  })
-  const result = {} as Record<Harness, HarnessCompatibility>
-  for (const harness of HarnessSchema.options) {
-    const native =
-      (harness === 'claude-code' && dialect === 'claude') ||
-      (harness === 'cursor' && dialect === 'cursor') ||
-      (harness === 'codex' && dialect === 'openai')
-    if (types.includes('executable'))
-      result[harness] = make('unsupported', [
-        'Executable components require harness-specific execution authority.',
-      ])
-    else if (types.includes('unknown'))
-      result[harness] = make('unknown', [
-        'The plugin content was not classified into a supported component type.',
-      ])
-    else if (native && sensitive.length === 0)
-      result[harness] = make('native', [
-        `The ${dialect} marketplace dialect matches the ${harness} harness.`,
-      ])
-    else if (sensitive.length > 0 && ['pi', 'hermes', 'opencode'].includes(harness))
-      result[harness] = make('partially-supported', [
-        `Sensitive capabilities require ${harness} policy and runtime review.`,
-        ...sensitive.map((type) => `Capability ${type} is not granted by this catalog.`),
-      ])
-    else if (
-      types.every((type) => ['skill', 'rule', 'mcp-server', 'command', 'agent'].includes(type))
-    )
-      result[harness] = make(
-        native ? 'native' : 'portable',
-        native
-          ? [`The ${dialect} marketplace dialect matches the ${harness} harness.`]
-          : ['Files can be copied or translated into the harness layout.']
-      )
-    else
-      result[harness] = make('requires-translation', [
-        'One or more capabilities need a harness-specific projection.',
-      ])
-  }
-  return result
-}
-
-type MarketplaceDialectName = 'openai' | 'cursor' | 'claude'
-
-function createSecurity(
-  capabilities: readonly Capability[],
-  policy: CatalogPolicy,
-  metadataOnly: boolean
-): SecurityClassification {
-  const sensitive = [
-    ...new Set(
-      capabilities
-        .filter((capability) => policy.sensitiveCapabilityTypes.includes(capability.type))
-        .map((capability) => capability.type)
-    ),
-  ].toSorted()
-  const reasons =
-    sensitive.length > 0
-      ? sensitive.map((type) => `Contains ${type} capability metadata.`)
-      : metadataOnly
-        ? ['Content was not fetched in metadata-only mode.']
-        : ['No permission-sensitive executable capability was detected.']
-  return {
-    level: sensitive.length > 0 ? 'sensitive' : metadataOnly ? 'review' : 'low',
-    reasons,
-    permissionSensitiveChanges: sensitive,
-    contentResolution: metadataOnly ? 'metadata-only' : 'complete',
-  }
-}
-
-function findLicense(
-  entry: MarketplacePluginEntry,
-  metadata?: Record<string, unknown>
-): LicenseMetadata {
-  const candidate = stringValue(metadata?.license) ?? stringValue(entry.raw.license)
-  if (!candidate) return { name: 'Unknown', source: 'unknown' }
-  return {
-    name: candidate,
-    ...(candidate.startsWith('http') ? { url: candidate } : {}),
-    source: metadata?.license !== undefined ? 'plugin-manifest' : 'marketplace-entry',
-  }
-}
-
-function createSourcesLock(sources: readonly ResolvedSource[]): SourcesLock {
-  const entries: SourceLockEntry[] = sources
-    .map((source) => ({
-      sourceId: source.config.sourceId,
-      repositoryUrl: canonicalRepositoryUrl(source.config.repositoryUrl),
-      defaultBranch: source.config.defaultBranch,
-      resolvedCommitSha: source.commitSha,
-      manifestPath: source.config.manifestPath,
-      marketplaceDialect: source.config.marketplaceDialect,
-      sourceManifestDigest: source.manifestDigest,
-      retrievedAt: source.retrievedAt,
-      synchronizationStatus: 'synchronized' as const,
-      pluginPins: source.pluginPins.map((pin) => ({ ...pin })),
-    }))
-    .toSorted((left, right) => left.sourceId.localeCompare(right.sourceId))
-  const body = { schemaVersion: 1 as const, sources: entries }
-  return SourcesLockSchema.parse({
-    ...body,
-    lockId: `lock:${digest(body).slice('sha256:'.length)}`,
-  })
-}
-
-/**
- * Orders plugins so each category's curated leading products come first, in
- * the configured order. Consumers preview the head of each category, so this
- * ordering decides what users see before expanding.
- */
-export function orderLeadingPlugins<
-  T extends {
-    readonly plugins: readonly {
-      categories: readonly string[]
-      upstreamPluginName: string
-    }[]
-  },
->(catalog: T, leading?: Record<string, readonly string[]>): T {
-  if (!leading) return catalog
-  const leadRank = new Map<string, number>()
-  for (const [category, names] of Object.entries(leading)) {
-    names.forEach((name, index) => {
-      const key = `${category}::${name}`
-      if (!leadRank.has(key)) leadRank.set(key, index)
-    })
-  }
-  const rank = (plugin: T['plugins'][number]): number => {
-    let best = Number.POSITIVE_INFINITY
-    for (const category of plugin.categories) {
-      const value = leadRank.get(`${category}::${plugin.upstreamPluginName}`)
-      if (value !== undefined && value < best) best = value
-    }
-    return best
-  }
-  return {
-    ...catalog,
-    plugins: catalog.plugins.toSorted((left, right) => rank(left) - rank(right)),
-  }
-}
-
-export function createArtifacts(
-  catalog: Catalog,
-  lock: SourcesLock,
-  options: ConsumerIndexOptions = {}
-): GeneratedArtifacts {
-  const index = buildConsumerIndex({
-    catalog,
-    ...(options.leading ? { leading: options.leading } : {}),
-    ...(options.topCount !== undefined ? { topCount: options.topCount } : {}),
-    ...(options.productPreference ? { preference: options.productPreference } : {}),
-    ...(options.publicationRepositoryUrl
-      ? { publicationRepositoryUrl: options.publicationRepositoryUrl }
-      : {}),
-    ...(options.publicationAssetsBaseUrl
-      ? { publicationAssetsBaseUrl: options.publicationAssetsBaseUrl }
-      : {}),
-    ...(options.publicationCatalogsBaseUrl
-      ? { publicationCatalogsBaseUrl: options.publicationCatalogsBaseUrl }
-      : {}),
-  })
-  const summary = {
-    schemaVersion: 1,
-    catalogId: catalog.catalogId,
-    generatedAt: catalog.generatedAt,
-    sourceCount: catalog.sources.length,
-    pluginCount: catalog.plugins.length,
-    categories: [...new Set(catalog.plugins.flatMap((plugin) => plugin.categories))].toSorted(),
-    productGroups: [
-      ...new Set(catalog.plugins.map((plugin) => plugin.productGroupingKey)),
-    ].toSorted(),
-    search: catalog.plugins
-      .map((plugin) => ({
-        pluginId: plugin.pluginId,
-        text: `${plugin.displayName} ${plugin.description} ${plugin.keywords.join(' ')}`.trim(),
-      }))
-      .toSorted((left, right) => left.pluginId.localeCompare(right.pluginId)),
-  }
-  const compatibility = {
-    schemaVersion: 1,
-    catalogId: catalog.catalogId,
-    plugins: catalog.plugins.map((plugin) => ({
-      pluginId: plugin.pluginId,
-      harnessCompatibility: plugin.harnessCompatibility,
-    })),
-  }
-  // Navigation stays small and points at the shards a client then fetches:
-  // `shelf-*` for a default view, `category-*` for "view more", and
-  // `catalog-index.v1.json` for the complete product list.
-  const navigation = {
-    schemaVersion: 1,
-    catalogId: catalog.catalogId,
-    generatedAt: catalog.generatedAt,
-    topCount: index.topCount,
-    sourcePreference: index.sourcePreference,
-    counts: index.counts,
-    catalogIndexArtifact: CATALOG_INDEX_ARTIFACT,
-    iconCoverage: iconCoverage(index),
-    // The index URL rides in the navigation artifact so a client can fetch the
-    // browsing index from the publication it was told about, verify it against
-    // the digest in integrity.json, and never compose a URL or need this
-    // service to proxy it. Absent for an unpublished build.
-    ...(options.publicationCatalogsBaseUrl
-      ? {
-          catalogIndexUrl: `${options.publicationCatalogsBaseUrl}/${catalog.catalogId.slice('catalog:'.length)}/${CATALOG_INDEX_ARTIFACT}`,
-        }
-      : options.publicationAssetsBaseUrl
-        ? { catalogIndexUrl: `${options.publicationAssetsBaseUrl}/${CATALOG_INDEX_ARTIFACT}` }
-        : options.publicationRepositoryUrl
-          ? {
-              catalogIndexUrl: immutableAssetUrl(
-                options.publicationRepositoryUrl,
-                catalog.catalogId,
-                CATALOG_INDEX_ARTIFACT
-              ),
-            }
-          : {}),
-    // Marks ride in the navigation artifact so a client that already receives it
-    // renders compiled brand marks without fetching the browsing index. Keys are
-    // sorted for a stable artifact.
-    brandMarks: Object.fromEntries(
-      Object.keys(index.products)
-        .toSorted()
-        .flatMap((productKey) => {
-          const assetUrl = index.products[productKey]?.icon?.assetUrl
-          return assetUrl ? [[productKey, assetUrl] as const] : []
-        })
-    ),
-    categories: index.categories,
-    diagnostics: options.curationDiagnostics === false ? [] : index.diagnostics,
-  }
-  const shards: Record<string, string> = {
-    [CATALOG_INDEX_ARTIFACT]: json({
-      schemaVersion: 1,
-      catalogId: catalog.catalogId,
-      generatedAt: catalog.generatedAt,
-      topCount: index.topCount,
-      sourcePreference: index.sourcePreference,
-      counts: index.counts,
-      products: index.products,
-      categories: index.categories.map((category) => ({
-        category: category.category,
-        productCount: category.productCount,
-        productKeys: category.productKeys,
-      })),
-    }),
-  }
-  for (const category of index.categories) {
-    shards[category.shelfArtifact] = json({
-      schemaVersion: 1,
-      catalogId: catalog.catalogId,
-      category: category.category,
-      topCount: index.topCount,
-      products: category.topProductKeys.map((productKey) => index.products[productKey]),
-    })
-    shards[category.listArtifact] = json({
-      schemaVersion: 1,
-      catalogId: catalog.catalogId,
-      category: category.category,
-      productCount: category.productCount,
-      pluginCount: category.pluginCount,
-      products: category.productKeys.map((productKey) => index.products[productKey]),
-    })
-  }
-  const files: Record<string, string> = {
-    'catalog.v1.json': json(catalog),
-    'catalog-summary.v1.json': json(summary),
-    'sources.lock.json': json(lock),
-    'compatibility.v1.json': json(compatibility),
-    'categories.v1.json': json(navigation),
-    ...shards,
-  }
-  const integrityBody = {
-    schemaVersion: 1,
-    catalogId: catalog.catalogId,
-    // An artifact's digest is the canonical digest of its text, not a hash of
-    // the file bytes: consumers read the artifact as a string and compare it
-    // with `canonicalDigest`, so a checker hashing the raw bytes will disagree
-    // with every published release. Mirrored marks below are the byte case,
-    // because a client stores those bytes.
-    files: Object.fromEntries(
-      Object.entries(files)
-        .toSorted()
-        .map(([name, content]) => [name, digest(content)])
-    ),
-    // Mirrored brand marks are published next to the artifacts, never inside
-    // them: the digest and size let a consumer or the release check verify the
-    // bytes it fetched without trusting the release listing.
-    assets: iconAssets(index),
-  }
-  return { ...files, 'integrity.json': json(integrityBody) } as GeneratedArtifacts
-}
-
-export interface PublishedAsset {
-  readonly name: string
-  readonly digest: string
-  readonly bytes: number
-  readonly contentType: string
-  /** `content` mirrors a plugin file; `favicon` mirrors the product site's icon. */
-  readonly kind: 'content' | 'favicon'
-  /** Upstream path or URL the bytes came from, for provenance. */
-  readonly origin: string
-}
-
-/** Every mirrored icon in the catalog, deduplicated by asset name. */
-export function iconAssets(index: ConsumerIndex): readonly PublishedAsset[] {
-  const assets = new Map<string, PublishedAsset>()
-  for (const product of Object.values(index.products)) {
-    if (!product.icon) continue
-    assets.set(product.icon.asset, {
-      name: product.icon.asset,
-      digest: product.icon.digest,
-      bytes: product.icon.bytes,
-      contentType: product.icon.contentType,
-      kind: product.icon.kind,
-      origin:
-        product.icon.kind === 'content' ? (product.icon.path ?? '') : (product.icon.url ?? ''),
-    })
-  }
-  return [...assets.values()].toSorted((left, right) => left.name.localeCompare(right.name))
-}
-
-export async function writeArtifacts(
-  generatedDirectory: string,
-  artifacts: GeneratedArtifacts
-): Promise<void> {
-  const parent = dirname(generatedDirectory)
-  await fs.mkdir(parent, { recursive: true })
-  const temporary = await fs.mkdtemp(join(parent, '.catalog-'))
-  try {
-    for (const [name, content] of Object.entries(artifacts))
-      await fs.writeFile(join(temporary, name), content, 'utf8')
-    const backup = `${generatedDirectory}.previous`
-    await fs.rm(backup, { recursive: true, force: true })
-    let movedExisting = false
-    try {
-      await fs.rename(generatedDirectory, backup)
-      movedExisting = true
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
-    }
-    try {
-      await fs.rename(temporary, generatedDirectory)
-    } catch (error) {
-      if (movedExisting) await fs.rename(backup, generatedDirectory)
-      throw error
-    }
-    if (movedExisting) await fs.rm(backup, { recursive: true, force: true })
-  } finally {
-    await fs.rm(temporary, { recursive: true, force: true })
-  }
-}
-
-export function verifyArtifacts(artifacts: GeneratedArtifacts): void {
-  const parsedCatalog = CatalogSchema.parse(JSON.parse(artifacts['catalog.v1.json']))
-  verifyCatalogReferences(parsedCatalog)
-  const lock = SourcesLockSchema.parse(JSON.parse(artifacts['sources.lock.json']))
-  const summary = JSON.parse(artifacts['catalog-summary.v1.json']) as {
-    schemaVersion?: unknown
-    catalogId?: unknown
-    sourceCount?: unknown
-    pluginCount?: unknown
-    search?: unknown
-  }
-  const compatibility = JSON.parse(artifacts['compatibility.v1.json']) as {
-    schemaVersion?: unknown
-    catalogId?: unknown
-    plugins?: unknown
-  }
-  const categories = JSON.parse(artifacts['categories.v1.json']) as {
-    schemaVersion?: unknown
-    catalogId?: unknown
-    topCount?: unknown
-    counts?: { plugins?: unknown; products?: unknown; redundantPlugins?: unknown }
-    categories?: unknown
-    products?: unknown
-    diagnostics?: unknown
-  }
-  const integrity = JSON.parse(artifacts['integrity.json']) as {
-    schemaVersion?: unknown
-    catalogId?: unknown
-    files?: Record<string, string>
-    assets?: unknown
-  }
-  if (parsedCatalog.sources.length !== lock.sources.length)
-    throw new Error('INTEGRITY_SOURCE_COUNT_MISMATCH')
-  if (
-    summary.schemaVersion !== 1 ||
-    summary.catalogId !== parsedCatalog.catalogId ||
-    summary.sourceCount !== parsedCatalog.sources.length ||
-    summary.pluginCount !== parsedCatalog.plugins.length ||
-    !Array.isArray(summary.search) ||
-    compatibility.schemaVersion !== 1 ||
-    compatibility.catalogId !== parsedCatalog.catalogId ||
-    !Array.isArray(compatibility.plugins) ||
-    compatibility.plugins.length !== parsedCatalog.plugins.length ||
-    categories.schemaVersion !== 1 ||
-    categories.catalogId !== parsedCatalog.catalogId ||
-    !Array.isArray(categories.categories) ||
-    (categories.products !== undefined &&
-      (typeof categories.products !== 'object' || categories.products === null)) ||
-    (categories.diagnostics !== undefined && !Array.isArray(categories.diagnostics)) ||
-    integrity.schemaVersion !== 1 ||
-    integrity.catalogId !== parsedCatalog.catalogId ||
-    !integrity.files ||
-    (integrity.assets !== undefined && !Array.isArray(integrity.assets))
-  ) {
-    throw new Error('INTEGRITY_ARTIFACT_METADATA_MISMATCH')
-  }
-  // The published file set is exactly what integrity.json enumerates, so the
-  // shards can grow with the category configuration without a fixed list here.
-  for (const name of Object.keys(artifacts))
-    if (name !== 'integrity.json' && integrity.files?.[name] === undefined)
-      throw new Error(`INTEGRITY_FILE_SET_MISMATCH: ${name}`)
-  for (const [name, expected] of Object.entries(integrity.files ?? {})) {
-    const content = artifacts[name]
-    if (content === undefined) throw new Error(`INTEGRITY_FILE_SET_MISMATCH: ${name}`)
-    if (digest(content) !== expected) throw new Error(`INTEGRITY_DIGEST_MISMATCH: ${name}`)
-  }
-  const indexArtifact = artifacts[CATALOG_INDEX_ARTIFACT]
-  const verification = verifyConsumerIndex(
-    artifacts['categories.v1.json'],
-    parsedCatalog,
-    indexArtifact
-  )
-  if (verification.hasConsumerIndex && indexArtifact === undefined)
-    throw new Error(`SHARD_MISSING: ${CATALOG_INDEX_ARTIFACT}`)
-  for (const shard of verification.shards)
-    verifyShardArtifact(shard, artifacts[shard.name], verification, parsedCatalog.catalogId)
-  verifyIconAssets(integrity.assets, verification)
-}
-
-/**
- * Re-checks one consumer shard against the navigation index: a shelf carries
- * exactly the curated products in order, and a category list carries exactly
- * the category's products in order. The expected catalog ID must come from a
- * separately verified catalog, not from the shard being checked.
- */
-export function verifyShardArtifact(
-  shard: ShardArtifact,
-  content: string | undefined,
-  verification: ConsumerIndexVerification,
-  catalogId: string
-): void {
-  if (typeof catalogId !== 'string' || !/^catalog:[a-f0-9]{64}$/.test(catalogId))
-    throw new Error('SHARD_CATALOG_ID_REQUIRED')
-  if (content === undefined) throw new Error(`SHARD_MISSING: ${shard.name}`)
-  const parsed = JSON.parse(content) as {
-    schemaVersion?: unknown
-    catalogId?: unknown
-    category?: unknown
-    topCount?: unknown
-    products?: unknown
-  }
-  if (
-    parsed.schemaVersion !== 1 ||
-    parsed.catalogId !== catalogId ||
-    (shard.kind !== 'index' && parsed.category !== shard.category)
-  )
-    throw new Error(`SHARD_IDENTITY_MISMATCH: ${shard.name}`)
-  // The index shard carries products keyed by productKey; the shelf and list
-  // shards carry them as ordered arrays.
-  const products: readonly ConsumerProduct[] =
-    shard.kind === 'index'
-      ? Object.values((parsed.products ?? {}) as Record<string, ConsumerProduct>)
-      : (parsed.products as readonly ConsumerProduct[])
-  if (!Array.isArray(products)) throw new Error(`SHARD_PRODUCTS_INVALID: ${shard.name}`)
-  const keys = products.map((product) => product.productKey)
-  if (new Set(keys).size !== keys.length) throw new Error(`SHARD_DUPLICATE_PRODUCT: ${shard.name}`)
-  if (shard.kind === 'index') {
-    const expected = Object.keys(verification.products ?? {}).toSorted()
-    if (keys.toSorted().join('\n') !== expected.join('\n'))
-      throw new Error('SHARD_INDEX_MEMBERSHIP_MISMATCH')
-    return
-  }
-  const category = verification.categories?.find((item) => item.category === shard.category)
-  if (!category) throw new Error(`SHARD_CATEGORY_UNKNOWN: ${shard.name}`)
-  const expected = shard.kind === 'shelf' ? category.topProductKeys : category.productKeys
-  if (keys.join('\n') !== expected.join('\n'))
-    throw new Error(`SHARD_ORDER_MISMATCH: ${shard.name}`)
-  for (const product of products) {
-    const index = verification.products?.[product.productKey]
-    if (!index || digest(index) !== digest(product))
-      throw new Error(`SHARD_PRODUCT_MISMATCH: ${shard.name}: ${product.productKey}`)
-  }
-}
-
-/** Every mirrored icon is declared once, with the digest the index advertises. */
-function verifyIconAssets(assets: unknown, verification: ConsumerIndexVerification): void {
-  const declared = (assets ?? []) as readonly PublishedAsset[]
-  if (!Array.isArray(declared)) throw new Error('INTEGRITY_ASSETS_INVALID')
-  const referenced = new Map<string, PublishedAsset>()
-  for (const product of Object.values(verification.products ?? {})) {
-    if (!product.icon) continue
-    const existing = referenced.get(product.icon.asset)
-    if (existing && existing.digest !== product.icon.digest)
-      throw new Error(`ICON_ASSET_DIGEST_CONFLICT: ${product.icon.asset}`)
-    referenced.set(product.icon.asset, {
-      name: product.icon.asset,
-      digest: product.icon.digest,
-      bytes: product.icon.bytes,
-      contentType: product.icon.contentType,
-      kind: product.icon.kind,
-      origin:
-        product.icon.kind === 'content' ? (product.icon.path ?? '') : (product.icon.url ?? ''),
-    })
-  }
-  if (declared.length !== referenced.size) throw new Error('INTEGRITY_ASSET_SET_MISMATCH')
-  for (const asset of declared) {
-    const expected = referenced.get(asset.name)
-    if (!expected) throw new Error(`INTEGRITY_ASSET_UNDECLARED: ${asset.name}`)
-    if (
-      expected.digest !== asset.digest ||
-      expected.bytes !== asset.bytes ||
-      expected.contentType !== asset.contentType ||
-      expected.kind !== asset.kind ||
-      expected.origin !== asset.origin
-    )
-      throw new Error(`INTEGRITY_ASSET_MISMATCH: ${asset.name}`)
-  }
-}
-
-/**
- * Re-checks the published consumer index against the catalog it indexes. The
- * index is what Adea renders directly, so a contradiction between the two
- * artifacts must never reach a release. Snapshots published before the index
- * existed carry membership only; those are still membership-checked and
- * reported as `hasConsumerIndex: false`.
- */
-export function verifyConsumerIndex(
-  content: string,
-  catalog: Pick<Catalog, 'plugins'>,
-  indexContent?: string
-): ConsumerIndexVerification {
-  const index = JSON.parse(content) as Partial<ConsumerIndex>
-  const knownPlugins = new Map(catalog.plugins.map((plugin) => [plugin.pluginId, plugin]))
-  // Products live in the index shard; the navigation artifact only points at it.
-  const shard = indexContent ? (JSON.parse(indexContent) as Partial<ConsumerIndex>) : undefined
-  const products =
-    shard && typeof shard.products === 'object' && shard.products !== null
-      ? shard.products
-      : typeof index.products === 'object' && index.products !== null
-        ? index.products
-        : undefined
-  const diagnostics = Array.isArray(index.diagnostics) ? index.diagnostics : []
-  for (const category of index.categories ?? []) {
-    const members = catalog.plugins.filter((plugin) =>
-      plugin.categories.includes(category.category)
-    )
-    if (category.pluginCount !== undefined && category.pluginCount !== members.length)
-      throw new Error(`CONSUMER_INDEX_PLUGIN_COUNT_MISMATCH: ${category.category}`)
-    if (category.pluginIds.length !== members.length)
-      throw new Error(`CONSUMER_INDEX_PLUGIN_LIST_MISMATCH: ${category.category}`)
-    if (new Set(category.pluginIds).size !== category.pluginIds.length)
-      throw new Error(`CONSUMER_INDEX_DUPLICATE_PLUGIN: ${category.category}`)
-    for (const pluginId of category.pluginIds) {
-      const plugin = knownPlugins.get(pluginId)
-      if (!plugin || !plugin.categories.includes(category.category))
-        throw new Error(`CONSUMER_INDEX_FOREIGN_PLUGIN: ${category.category}: ${pluginId}`)
-    }
-    if (!products) continue
-    if (category.productKeys === undefined || category.topProductKeys === undefined)
-      throw new Error(`CONSUMER_INDEX_PRODUCTS_INCOMPLETE: ${category.category}`)
-    if (new Set(category.productKeys).size !== category.productKeys.length)
-      throw new Error(`CONSUMER_INDEX_DUPLICATE_PRODUCT: ${category.category}`)
-    for (const productKey of category.productKeys) {
-      const product = products[productKey]
-      if (!product) throw new Error(`CONSUMER_INDEX_UNKNOWN_PRODUCT: ${productKey}`)
-      if (!product.categories.includes(category.category))
-        throw new Error(`CONSUMER_INDEX_PRODUCT_CATEGORY_MISMATCH: ${productKey}`)
-    }
-    if (category.productCount !== category.productKeys.length)
-      throw new Error(`CONSUMER_INDEX_PRODUCT_COUNT_MISMATCH: ${category.category}`)
-    const topCount = index.topCount
-    if (topCount === undefined || !Number.isInteger(topCount) || topCount < 0)
-      throw new Error('CONSUMER_INDEX_TOP_COUNT_INVALID')
-    if (category.topProductKeys.length > topCount)
-      throw new Error(`CONSUMER_INDEX_TOP_OVERFLOW: ${category.category}`)
-    const shelved = new Set<string>()
-    for (const product of Object.values(products)) {
-      // Indexes published before the install facts existed carry no `release`,
-      // and are still valid; a record that does carry one must agree with the
-      // catalog it claims to describe.
-      if (product.release) {
-        const plugin = knownPlugins.get(product.pluginId)
-        const release = plugin?.availableReleases.find(
-          (candidate) => candidate.releaseId === plugin.currentReleaseId
-        )
-        if (
-          !plugin ||
-          !release ||
-          product.release.releaseId !== release.releaseId ||
-          product.release.canonicalContentDigest !== release.canonicalContentDigest ||
-          product.release.sourceRevision !== release.resolvedCommitSha ||
-          product.provenance?.resolvedCommitSha !== release.resolvedCommitSha
-        )
-          throw new Error(`CONSUMER_INDEX_RELEASE_MISMATCH: ${product.productKey}`)
-      }
-      const icon = product.icon
-      if (!icon?.assetUrl) continue
-      if (!icon.assetUrl.startsWith('https://') || !icon.assetUrl.endsWith(`/${icon.asset}`))
-        throw new Error(`CONSUMER_INDEX_ASSET_URL_INVALID: ${icon.asset}`)
-    }
-    for (const productKey of category.topProductKeys) {
-      if (!category.productKeys.includes(productKey))
-        throw new Error(`CONSUMER_INDEX_TOP_NOT_MEMBER: ${category.category}: ${productKey}`)
-      if (shelved.has(productKey)) throw new Error(`CONSUMER_INDEX_TOP_REPEATED: ${productKey}`)
-      shelved.add(productKey)
-    }
-  }
-  if (products) {
-    // A product headlines one category only, so no product is shelved twice.
-    const claimed = new Set<string>()
-    for (const category of index.categories ?? [])
-      for (const productKey of category.topProductKeys ?? []) {
-        if (claimed.has(productKey))
-          throw new Error(`CONSUMER_INDEX_TOP_CROSS_CATEGORY: ${productKey}`)
-        claimed.add(productKey)
-      }
-    for (const [productKey, product] of Object.entries(products)) {
-      if (productKey !== product.productKey) throw new Error('CONSUMER_INDEX_PRODUCT_KEY_MISMATCH')
-      if (product.variantPluginIds[0] !== product.pluginId)
-        throw new Error(`CONSUMER_INDEX_CANONICAL_NOT_FIRST: ${productKey}`)
-      const variants = new Set(
-        product.variantPluginIds.map((pluginId) => {
-          const plugin = knownPlugins.get(pluginId)
-          if (!plugin) throw new Error(`CONSUMER_INDEX_UNKNOWN_PLUGIN: ${pluginId}`)
-          if (plugin.productGroupingKey !== productKey)
-            throw new Error(`CONSUMER_INDEX_VARIANT_PRODUCT_MISMATCH: ${pluginId}`)
-          return pluginId
-        })
-      )
-      if (variants.size !== product.variantPluginIds.length)
-        throw new Error(`CONSUMER_INDEX_DUPLICATE_VARIANT: ${productKey}`)
-    }
-    const counts = shard?.counts ?? index.counts
-    if (counts?.plugins !== catalog.plugins.length) throw new Error('CONSUMER_INDEX_TOTAL_MISMATCH')
-    if (counts?.products !== Object.keys(products).length)
-      throw new Error('CONSUMER_INDEX_PRODUCT_TOTAL_MISMATCH')
-    if (counts?.redundantPlugins !== catalog.plugins.length - counts.products)
-      throw new Error('CONSUMER_INDEX_REDUNDANCY_MISMATCH')
-    if (index.counts && shard?.counts && digest(index.counts) !== digest(shard.counts))
-      throw new Error('CONSUMER_INDEX_COUNTS_MISMATCH')
-    if (shard?.topCount !== undefined && index.topCount !== shard.topCount)
-      throw new Error('CONSUMER_INDEX_TOP_COUNT_MISMATCH')
-  }
-  if (products && index.iconCoverage) {
-    const expected = iconCoverage({ products })
-    if (
-      index.iconCoverage.total !== expected.total ||
-      index.iconCoverage.content !== expected.content ||
-      index.iconCoverage.favicon !== expected.favicon ||
-      index.iconCoverage.monogramOnly !== expected.monogramOnly ||
-      index.iconCoverage.monogramProductKeys.join('\n') !== expected.monogramProductKeys.join('\n')
-    )
-      throw new Error('CONSUMER_INDEX_ICON_COVERAGE_MISMATCH')
-  }
-  const shards: ShardArtifact[] = [
-    ...(products ? [{ name: CATALOG_INDEX_ARTIFACT, kind: 'index' as const }] : []),
-    ...(index.categories ?? []).flatMap((category) =>
-      products && category.shelfArtifact && category.listArtifact
-        ? [
-            { name: category.shelfArtifact, kind: 'shelf' as const, category: category.category },
-            { name: category.listArtifact, kind: 'list' as const, category: category.category },
-          ]
-        : []
-    ),
-  ]
-  return {
-    hasConsumerIndex: products !== undefined,
-    diagnostics,
-    ...(products ? { counts: index.counts as ConsumerIndex['counts'] } : {}),
-    ...(products && index.topCount !== undefined ? { topCount: index.topCount } : {}),
-    ...(products ? { products, categories: index.categories ?? [] } : {}),
-    shards: products ? shards : [],
-  }
-}
-
-export function verifyCatalogReferences(
-  catalog: Catalog,
-  policy: CatalogPolicy = DEFAULT_POLICY
-): void {
-  for (const source of catalog.sources) {
-    assertRepositoryAllowed(source.repositoryUrl, policy)
-    validateCatalogPath(source.manifestPath, 'SOURCE_MANIFEST_PATH_INVALID')
-  }
-  for (const plugin of catalog.plugins) {
-    assertRepositoryAllowed(plugin.provenance.repositoryUrl, policy)
-    validateCatalogPath(plugin.provenance.pluginSubdirectory, 'PROVENANCE_PATH_INVALID')
-    for (const release of plugin.availableReleases) {
-      assertRepositoryAllowed(release.resolvedRepositoryUrl, policy)
-      validateCatalogPath(release.pluginSubdirectory, 'RELEASE_PATH_INVALID')
-      for (const path of release.fileIndex) validateCatalogPath(path, 'RELEASE_FILE_PATH_INVALID')
-    }
-  }
-}
-
-function validateCatalogPath(path: string, code: string): void {
-  if (path !== '.') safeRelativePath(path, code)
-}
-
-function createChangeReport(
-  catalog: Catalog,
-  lock: SourcesLock,
-  existingLock?: SourcesLock,
-  existingCatalog?: Catalog,
-  skippedPlugins: readonly SkippedPlugin[] = []
-): ChangeReport {
-  const changedSources = existingLock
-    ? lock.sources
-        .filter((source) =>
-          (() => {
-            const previous = existingLock.sources.find(
-              (candidate) => candidate.sourceId === source.sourceId
-            )
-            return (
-              !previous ||
-              previous?.resolvedCommitSha !== source.resolvedCommitSha ||
-              previous.sourceManifestDigest !== source.sourceManifestDigest ||
-              digest(previous.pluginPins) !== digest(source.pluginPins)
-            )
-          })()
-        )
-        .map((source) => source.sourceId)
-    : lock.sources.map((source) => source.sourceId)
-  const previousPlugins = new Map(
-    existingCatalog?.plugins.map((plugin) => [plugin.pluginId, plugin]) ?? []
-  )
-  const currentPlugins = new Map(catalog.plugins.map((plugin) => [plugin.pluginId, plugin]))
-  const addedPlugins = catalog.plugins
-    .filter((plugin) => !previousPlugins.has(plugin.pluginId))
-    .map((plugin) => plugin.pluginId)
-  const removedPlugins = [...previousPlugins.keys()].filter(
-    (pluginId) => !currentPlugins.has(pluginId)
-  )
-  const changedPlugins = catalog.plugins
-    .filter(
-      (plugin) =>
-        previousPlugins.get(plugin.pluginId)?.currentReleaseId !== plugin.currentReleaseId &&
-        previousPlugins.has(plugin.pluginId)
-    )
-    .map((plugin) => plugin.pluginId)
-  return {
-    schemaVersion: 1,
-    changedSources: changedSources.toSorted(),
-    addedPlugins: addedPlugins.toSorted(),
-    removedPlugins: removedPlugins.toSorted(),
-    changedPlugins: changedPlugins.toSorted(),
-    skippedPlugins,
-    permissionSensitiveChanges: catalog.plugins
-      .flatMap((plugin) =>
-        plugin.securityClassification.permissionSensitiveChanges.map(
-          (type) => `${plugin.pluginId}:${type}`
-        )
-      )
-      .toSorted(),
-    contentResolution:
-      skippedPlugins.length > 0
-        ? 'complete-with-skips'
-        : catalog.plugins.some(
-              (plugin) => plugin.securityClassification.contentResolution === 'metadata-only'
-            )
-          ? 'metadata-only'
-          : 'complete',
-  }
-}
-
-async function resolveSource(
-  config: SourceConfig,
-  mode: 'live' | 'offline',
-  fixtureRoot: string | undefined,
-  lock: SourcesLock | undefined,
-  fromLock: boolean
-): Promise<ResolvedSource> {
-  const manifestPath = safeRelativePath(config.manifestPath, 'SOURCE_MANIFEST_PATH_INVALID')
-  const locked = lock?.sources.find((entry) => entry.sourceId === config.sourceId)
-  if (fromLock && !locked) throw new Error(`SOURCE_LOCK_ENTRY_MISSING: ${config.sourceId}`)
-  const commitSha =
-    fromLock && locked
-      ? locked.resolvedCommitSha
-      : mode === 'offline'
-        ? (config.fixtureCommitSha ?? locked?.resolvedCommitSha)
-        : await resolveGitRef(config.repositoryUrl, `refs/heads/${config.defaultBranch}`)
-  if (!commitSha || !/^[a-f0-9]{40}$/.test(commitSha))
-    throw new Error(`SOURCE_COMMIT_UNRESOLVED: ${config.sourceId}`)
-  const manifestText =
-    mode === 'offline'
-      ? await readFixtureManifest({ ...config, manifestPath }, fixtureRoot)
-      : await fetchText(rawUrl(config.repositoryUrl, commitSha, manifestPath))
-  const parsed = parseMarketplaceManifest(parseJsonDocument(manifestText), config)
-  if (fromLock && locked && digest(manifestText) !== locked.sourceManifestDigest)
-    throw new Error(`SOURCE_LOCK_MANIFEST_MISMATCH: ${config.sourceId}`)
-  const pluginPins = await resolvePluginPins({
-    config,
-    parsed,
-    sourceCommitSha: commitSha,
-    lockedPins: locked?.pluginPins,
-    fromLock,
-    resolveExternalRefs: mode === 'live',
-  })
-  return {
-    config,
-    commitSha,
-    manifestText,
-    parsed,
-    pluginPins,
-    retrievedAt:
-      fromLock && locked
-        ? locked.retrievedAt
-        : mode === 'offline'
-          ? '2026-01-01T00:00:00.000Z'
-          : new Date().toISOString(),
-    manifestDigest: digest(manifestText),
-  }
-}
-
-async function resolvePluginPins(input: {
-  readonly config: SourceConfig
-  readonly parsed: ParsedMarketplace
-  readonly sourceCommitSha: string
-  readonly lockedPins: readonly PluginSourcePin[] | undefined
-  readonly fromLock: boolean
-  readonly resolveExternalRefs: boolean
-}): Promise<PluginSourcePin[]> {
-  const pins = await mapWithConcurrency(
-    input.parsed.entries,
-    8,
-    async (entry): Promise<PluginSourcePin> => {
-      if (entry.source.kind === 'local') {
-        return {
-          pluginName: entry.name,
-          repositoryUrl: canonicalRepositoryUrl(input.config.repositoryUrl),
-          pluginSubdirectory: entry.source.path,
-          resolvedCommitSha: input.sourceCommitSha,
-        }
-      }
-
-      const repositoryUrl = canonicalRepositoryUrl(entry.source.repositoryUrl)
-      const pluginSubdirectory = entry.source.subdirectory
-      // Existing locks describe the prior sync; only explicit replay freezes revisions.
-      const locked = input.fromLock
-        ? input.lockedPins?.find((pin) => pin.pluginName === entry.name)
-        : undefined
-      if (input.fromLock && !locked)
-        throw new Error(`SOURCE_LOCK_PLUGIN_PIN_MISSING: ${input.config.sourceId}:${entry.name}`)
-      if (locked) {
-        if (
-          locked.repositoryUrl !== repositoryUrl ||
-          locked.pluginSubdirectory !== pluginSubdirectory
-        ) {
-          throw new Error(`SOURCE_LOCK_PLUGIN_PIN_MISMATCH: ${input.config.sourceId}:${entry.name}`)
-        }
-        return locked
-      }
-
-      const resolvedCommitSha =
-        entry.source.sha ??
-        (input.resolveExternalRefs
-          ? await resolveGitRef(
-              repositoryUrl,
-              entry.source.ref?.startsWith('refs/')
-                ? entry.source.ref
-                : `refs/heads/${entry.source.ref ?? 'main'}`
-            )
-          : input.sourceCommitSha)
-      return { pluginName: entry.name, repositoryUrl, pluginSubdirectory, resolvedCommitSha }
-    }
-  )
-  return pins.toSorted((left, right) => left.pluginName.localeCompare(right.pluginName))
-}
-
-async function mapWithConcurrency<T, U>(
-  values: readonly T[],
-  concurrency: number,
-  mapper: (value: T, index: number) => Promise<U>
-): Promise<U[]> {
-  const results = Array.from<U>({ length: values.length })
-  let nextIndex = 0
-  const worker = async (): Promise<void> => {
-    while (true) {
-      const index = nextIndex++
-      if (index >= values.length) return
-      results[index] = await mapper(values[index]!, index)
-    }
-  }
-  await Promise.all(
-    Array.from({ length: Math.min(Math.max(concurrency, 1), values.length) }, () => worker())
-  )
-  return results
-}
-
-async function readFixtureManifest(
-  config: SourceConfig,
-  fixtureRoot: string | undefined
-): Promise<string> {
-  if (!fixtureRoot || !config.fixturePath)
-    throw new Error(`FIXTURE_ROOT_REQUIRED: ${config.sourceId}`)
-  return fs.readFile(join(resolve(fixtureRoot), config.fixturePath, config.manifestPath), 'utf8')
-}
-
-async function resolveGitRef(repositoryUrl: string, ref: string): Promise<string> {
-  const result = spawn('git', ['ls-remote', canonicalRepositoryUrl(repositoryUrl), ref], {
-    stdio: ['ignore', 'pipe', 'pipe'],
-  })
-  const [stdout, stderr, exitCode] = await Promise.all([
-    new Promise<string>((resolveOutput, reject) => {
-      const chunks: Buffer[] = []
-      result.stdout?.on('data', (chunk: Buffer) => chunks.push(chunk))
-      result.stdout?.on('error', reject)
-      result.stdout?.on('end', () => resolveOutput(Buffer.concat(chunks).toString('utf8')))
-    }),
-    new Promise<string>((resolveError) => {
-      const chunks: Buffer[] = []
-      result.stderr?.on('data', (chunk: Buffer) => chunks.push(chunk))
-      result.stderr?.on('error', () => resolveError(''))
-      result.stderr?.on('end', () => resolveError(Buffer.concat(chunks).toString('utf8')))
-    }),
-    new Promise<number | null>((resolveExit, reject) => {
-      result.on('error', reject)
-      result.on('close', (code) => resolveExit(code ?? 1))
-    }),
-  ])
-  if (exitCode !== 0)
-    throw new Error(`GIT_REF_LOOKUP_FAILED: ${repositoryUrl}:${ref}:${stderr.trim()}`)
-  const sha = stdout.trim().split(/\s+/)[0]
-  if (!sha || !/^[a-f0-9]{40}$/.test(sha))
-    throw new Error(`GIT_REF_NOT_FOUND: ${repositoryUrl}:${ref}`)
-  return sha
-}
-
-/** Raw content URL for one file at an immutable commit. */
-export function rawContentUrl(repositoryUrl: string, commitSha: string, path: string): string {
-  return rawUrl(repositoryUrl, commitSha, path)
-}
-
-/** Fetches bytes from an allow-listed upstream URL with the shared retry policy. */
-export async function fetchUpstreamBytes(url: string, signal?: AbortSignal): Promise<Uint8Array> {
-  const response = await fetchUpstream(url, {
-    headers: upstreamRequestHeaders(url),
-    ...(signal ? { signal } : {}),
-  })
-  if (!response.ok) throw new Error(`HTTP_FETCH_FAILED: ${response.status}: ${url}`)
-  return new Uint8Array(await response.arrayBuffer())
-}
-
-function rawUrl(repositoryUrl: string, commitSha: string, path: string): string {
-  const parsed = new URL(canonicalRepositoryUrl(repositoryUrl))
-  return `https://raw.githubusercontent.com${parsed.pathname}/${commitSha}/${path.split('/').map(encodeURIComponent).join('/')}`
-}
-
-async function fetchText(url: string): Promise<string> {
-  const response = await fetch(url, { headers: upstreamRequestHeaders(url) })
-  if (!response.ok) throw new Error(`HTTP_FETCH_FAILED: ${response.status}:${url}`)
-  return response.text()
-}
-
-const UPSTREAM_USER_AGENT = 'agent-hq-plugin-marketplace'
-
-/**
- * Hosts that may receive the repository credential.
- *
- * Everything else is fetched anonymously. The token this build runs with
- * authorises repository writes for the duration of the job, so a vendor
- * homepage, its icon CDN or any other third party must never be handed it.
- */
-const GITHUB_CREDENTIAL_HOSTS = /(^|\.)(github\.com|githubusercontent\.com)$/
-
-/**
- * Request headers for one upstream URL.
- *
- * The credential and GitHub's media type are attached only for GitHub hosts.
- * Sending them elsewhere is not merely a needless disclosure: `appwrite.io`
- * answers a page carrying an `Authorization` header with HTTP 500, and a CDN
- * asked for an image with `accept: application/vnd.github+json` can answer with
- * bytes that are not the mark. A build that did this dropped marks it had
- * already curated, and the curation verifier — which used its own anonymous
- * headers — could not see it.
- */
-export function upstreamRequestHeaders(url: string): Record<string, string> {
-  const anonymous = { 'user-agent': UPSTREAM_USER_AGENT }
-  let host: string
-  try {
-    host = new URL(url).hostname.toLowerCase()
-  } catch {
-    return anonymous
-  }
-  const token = process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN
-  if (!token || !GITHUB_CREDENTIAL_HOSTS.test(host)) return anonymous
-  return {
-    accept: 'application/vnd.github+json',
-    authorization: `Bearer ${token}`,
-    'user-agent': UPSTREAM_USER_AGENT,
-  }
-}
-
-/**
- * Fetches vendor-site documents exactly as a live build does.
- *
- * Shared with the curation verifier so both ask a vendor the same question: a
- * verifier with its own headers reports sites healthy that the build then fails
- * to resolve.
- *
- * `deadline` optionally bounds one product's whole resolution. The per-request
- * ceiling is always created fresh inside each fetch, so a caller that passes a
- * deadline — or shares one — can never hand later requests an already-expired
- * signal.
- */
-export function createSiteIconFetcher(deadline?: AbortSignal): SiteIconFetcher {
-  const bounded = (): AbortSignal => {
-    const ceiling = AbortSignal.timeout(SITE_FETCH_TIMEOUT_MS)
-    return deadline ? AbortSignal.any([deadline, ceiling]) : ceiling
-  }
-  return {
-    fetchText: async (url) => new TextDecoder().decode(await fetchUpstreamBytes(url, bounded())),
-    fetchBytes: (url) => fetchUpstreamBytes(url, bounded()),
-    digest: byteDigest,
-  }
-}
-
-/** Ceiling for a single product-site request during icon discovery. */
-export const SITE_FETCH_TIMEOUT_MS = 15_000
-
-const UPSTREAM_FETCH_MAX_ATTEMPTS = 3
-const UPSTREAM_FETCH_BASE_DELAY_MS = 1000
-const UPSTREAM_FETCH_MAX_DELAY_MS = 30000
-
-const UPSTREAM_WEATHER_SKIP_CODES: ReadonlySet<PluginSkipReasonCode> = new Set([
-  'PLUGIN_SOURCE_UNAVAILABLE',
-  'PLUGIN_FILE_UNAVAILABLE',
-  'PLUGIN_PATH_NOT_FOUND',
-])
-
-function upstreamRetryDelayMs(attempt: number, response?: Response): number {
-  const retryAfter = response?.headers.get('retry-after')
-  if (retryAfter !== null && retryAfter !== undefined) {
-    const seconds = Number(retryAfter)
-    if (Number.isFinite(seconds) && seconds >= 0)
-      return Math.min(seconds * 1000, UPSTREAM_FETCH_MAX_DELAY_MS)
-    const date = Date.parse(retryAfter)
-    if (!Number.isNaN(date))
-      return Math.min(Math.max(date - Date.now(), 0), UPSTREAM_FETCH_MAX_DELAY_MS)
-  }
-  return Math.min(UPSTREAM_FETCH_BASE_DELAY_MS * 2 ** attempt, UPSTREAM_FETCH_MAX_DELAY_MS)
-}
-
-function isRateLimitedUpstream(response: Response): boolean {
-  return (
-    response.headers.get('x-ratelimit-remaining') === '0' ||
-    response.headers.get('retry-after') !== null
-  )
-}
-
-function isRetryableUpstreamStatus(status: number, response?: Response): boolean {
-  if (status === 429) return true
-  if (status >= 500) return true
-  if (status === 403 && response !== undefined && isRateLimitedUpstream(response)) return true
-  return false
-}
-
-async function fetchUpstream(url: string, init: RequestInit): Promise<Response> {
-  let attempt = 0
-  for (;;) {
-    let response: Response
-    try {
-      response = await fetch(url, init)
-    } catch (error) {
-      if (init.signal?.aborted || attempt >= UPSTREAM_FETCH_MAX_ATTEMPTS - 1) throw error
-      await sleep(upstreamRetryDelayMs(attempt), undefined, { signal: init.signal ?? undefined })
-      attempt += 1
-      continue
-    }
-    if (
-      response.ok ||
-      !isRetryableUpstreamStatus(response.status, response) ||
-      attempt >= UPSTREAM_FETCH_MAX_ATTEMPTS - 1
-    )
-      return response
-    await response.body?.cancel().catch(() => {})
-    await sleep(upstreamRetryDelayMs(attempt, response), undefined, {
-      signal: init.signal ?? undefined,
-    })
-    attempt += 1
-  }
-}
-
-/**
- * Ceiling on bytes read out of one repository archive.
- *
- * The per-plugin policy still bounds what any single plugin may contain; this
- * only stops a decompression bomb from exhausting the build host, and it is
- * enforced while the stream is read rather than after it is buffered.
- */
-const MAX_ARCHIVE_BYTES = 512 * 1024 * 1024
-
-function concatChunks(chunks: readonly Uint8Array[], length: number): Uint8Array {
-  const out = new Uint8Array(length)
-  let offset = 0
-  for (const chunk of chunks) {
-    out.set(chunk, offset)
-    offset += chunk.byteLength
-  }
-  return out
-}
-
-/**
- * Read one GitHub repository tarball into path -> bytes.
- *
- * GitHub wraps every entry in a single top-level `<repo>-<sha>/` directory,
- * which is stripped so the keys match the tree API's repository-relative
- * paths. Only regular files are taken: directories, symlinks, hardlinks and
- * the `pax_global_header` record are skipped, so a link can never be
- * materialized as content. Every remaining path goes through
- * `safeRelativePath`, so an archive that tries to escape the repository is
- * rejected rather than partially trusted. This is a whole-repository archive
- * shared across plugins, so an oversized unrelated file is drained and
- * counted against the archive budget but not retained. The selected plugin's
- * files are checked against the tree before the archive is fetched and again
- * when its snapshot is validated.
- */
-export async function readArchiveFiles(
-  archive: Uint8Array,
-  policy: CatalogPolicy
-): Promise<Map<string, Uint8Array>> {
-  const files = new Map<string, Uint8Array>()
-  let totalBytes = 0
-  const parser = extract()
-  const gunzip = createGunzip()
-  const settled = new Promise<void>((resolveDone, rejectDone) => {
-    const fail = (error: unknown): void => {
-      gunzip.destroy()
-      parser.destroy()
-      rejectDone(error)
-    }
-    parser.on('entry', (header, stream, next) => {
-      const skip = (): void => {
-        stream.on('end', next)
-        stream.resume()
-      }
-      if (header.type !== 'file') return skip()
-      const segments = header.name.split('/')
-      if (segments.length < 2) return skip()
-      let path: string
-      try {
-        path = safeRelativePath(segments.slice(1).join('/'), 'TREE_PATH_INVALID')
-      } catch (error) {
-        return fail(error)
-      }
-      const chunks: Uint8Array[] = []
-      let length = 0
-      stream.on('data', (chunk: unknown) => {
-        const bytes = chunk as Uint8Array
-        length += bytes.byteLength
-        if (totalBytes + length > MAX_ARCHIVE_BYTES) {
-          fail(new Error('PLUGIN_SIZE_POLICY: archive'))
-          return
-        }
-        if (length <= policy.maxFileBytes) chunks.push(bytes)
-        else chunks.length = 0
-      })
-      stream.on('error', fail)
-      stream.on('end', () => {
-        try {
-          totalBytes += length
-          if (length <= policy.maxFileBytes) files.set(path, concatChunks(chunks, length))
-          next()
-        } catch (error) {
-          fail(error)
-        }
-      })
-      stream.resume()
-    })
-    parser.on('error', fail)
-    gunzip.on('error', fail)
-    parser.on('finish', () => resolveDone())
-  })
-  Readable.from([archive]).pipe(gunzip).pipe(parser)
-  await settled
-  return files
-}
-
-export class NetworkSnapshotLoader implements SnapshotLoader {
-  readonly #policy: CatalogPolicy
-  readonly #trees = new Map<string, Promise<readonly TreeEntry[]>>()
-  readonly #archives = new Map<string, Promise<ReadonlyMap<string, Uint8Array>>>()
-
-  constructor(policy: CatalogPolicy) {
-    this.#policy = policy
-  }
-
-  async load(
-    repositoryUrl: string,
-    commitSha: string,
-    pluginSubdirectory: string
-  ): Promise<Snapshot> {
-    const parsed = new URL(canonicalRepositoryUrl(repositoryUrl))
-    if (!['github.com', 'www.github.com'].includes(parsed.hostname))
-      throw new Error(`GIT_HOST_UNSUPPORTED: ${parsed.hostname}`)
-    const [owner, repo] = parsed.pathname.split('/').filter(Boolean)
-    if (!owner || !repo) throw new Error('GIT_REPOSITORY_INVALID')
-    const key = `${owner}/${repo}@${commitSha}`
-    let pendingTree = this.#trees.get(key)
-    if (!pendingTree) {
-      pendingTree = (async () => {
-        const treeUrl = `https://api.github.com/repos/${owner}/${repo}/git/trees/${commitSha}?recursive=1`
-        const response = await fetchUpstream(treeUrl, {
-          headers: upstreamRequestHeaders(treeUrl),
-        })
-        if (!response.ok)
-          throw new PluginSafetyError('PLUGIN_SOURCE_UNAVAILABLE', [`${owner}/${repo}`])
-        const payload = (await response.json()) as { truncated?: boolean; tree?: TreeEntry[] }
-        if (payload.truncated) throw new Error(`GIT_TREE_TRUNCATED: ${owner}/${repo}@${commitSha}`)
-        return (payload.tree ?? []).map((entry) => ({
-          ...entry,
-          path: safeRelativePath(entry.path, 'TREE_PATH_INVALID'),
-        }))
-      })().catch((error: unknown) => {
-        this.#trees.delete(key)
-        throw error
-      })
-      this.#trees.set(key, pendingTree)
-    }
-    const tree = await pendingTree
-    const prefix = pluginSubdirectory ? `${safeRelativePath(pluginSubdirectory)}/` : ''
-    const submodules = tree.filter(
-      (entry) =>
-        entry.path.startsWith(prefix) && (entry.type === 'commit' || entry.mode === '160000')
-    )
-    if (submodules.length > 0)
-      throw new Error(`GIT_SUBMODULE_UNSUPPORTED: ${repositoryUrl}:${pluginSubdirectory}`)
-    const selected = tree.filter((entry) => entry.type === 'blob' && entry.path.startsWith(prefix))
-    if (selected.length === 0)
-      throw new Error(`PLUGIN_PATH_NOT_FOUND: ${repositoryUrl}:${pluginSubdirectory}`)
-    const files = new Map<string, Uint8Array>()
-    const symlinks = tree
-      .filter((entry) => entry.mode === '120000' && entry.path.startsWith(prefix))
-      .map((entry) => entry.path)
-    if (selected.length > this.#policy.maxFilesPerPlugin) throw new Error('PLUGIN_TOO_MANY_FILES')
-    let totalSize = 0
-    for (const entry of selected) {
-      const size = entry.size ?? 0
-      if (size > this.#policy.maxFileBytes || totalSize + size > this.#policy.maxBytesPerPlugin)
-        throw new Error(`PLUGIN_SIZE_POLICY: ${entry.path}`)
-      totalSize += size
-    }
-    // The tree above already bounded this plugin before a byte was pulled, so
-    // the archive is the only unbounded read left and it is capped while it
-    // streams. One archive per repository replaces one request per file.
-    const archive = await this.#archiveFiles(key, owner, repo, commitSha)
-    for (const entry of selected) {
-      const bytes = archive.get(entry.path)
-      if (!bytes) throw new PluginSafetyError('PLUGIN_FILE_UNAVAILABLE', [entry.path])
-      if (bytes.byteLength > this.#policy.maxFileBytes)
-        throw new Error(`PLUGIN_FILE_TOO_LARGE: ${entry.path}`)
-      files.set(
-        prefix ? relative(prefix.slice(0, -1), entry.path).replaceAll('\\', '/') : entry.path,
-        bytes
-      )
-    }
-    return { files, symlinks }
-  }
-
-  /**
-   * One repository archive per (repository, commit), shared by every plugin
-   * that repository hosts.
-   */
-  async #archiveFiles(
-    key: string,
-    owner: string,
-    repo: string,
-    commitSha: string
-  ): Promise<ReadonlyMap<string, Uint8Array>> {
-    const cached = this.#archives.get(key)
-    if (cached) return cached
-    const pending = (async () => {
-      const url = `https://api.github.com/repos/${owner}/${repo}/tarball/${commitSha}`
-      const response = await fetchUpstream(url, { headers: upstreamRequestHeaders(url) })
-      if (!response.ok)
-        throw new PluginSafetyError('PLUGIN_SOURCE_UNAVAILABLE', [`${owner}/${repo}`])
-      return readArchiveFiles(new Uint8Array(await response.arrayBuffer()), this.#policy)
-    })().catch((error: unknown) => {
-      this.#archives.delete(key)
-      throw error
-    })
-    this.#archives.set(key, pending)
-    return pending
-  }
-}
-
-interface TreeEntry {
-  readonly path: string
-  readonly mode?: string
-  readonly type?: string
-  readonly size?: number
-}
-
-export class FixtureSnapshotLoader implements SnapshotLoader {
-  readonly #root: string
-  readonly #sources: ReadonlyMap<string, SourceConfig>
-
-  constructor(root: string, sources: readonly SourceConfig[]) {
-    this.#root = resolve(root)
-    this.#sources = new Map(
-      sources.map((source) => [canonicalRepositoryUrl(source.repositoryUrl), source])
-    )
-  }
-
-  async load(
-    repositoryUrl: string,
-    _commitSha: string,
-    pluginSubdirectory: string
-  ): Promise<Snapshot> {
-    const source = this.#sources.get(canonicalRepositoryUrl(repositoryUrl))
-    if (!source?.fixturePath) throw new Error(`FIXTURE_REPOSITORY_NOT_FOUND: ${repositoryUrl}`)
-    return snapshotFromDirectory(join(this.#root, source.fixturePath), pluginSubdirectory)
-  }
-}
-
-export class DirectorySnapshotLoader implements SnapshotLoader {
-  async load(
-    _repositoryUrl: string,
-    _commitSha: string,
-    pluginSubdirectory: string
-  ): Promise<Snapshot> {
-    throw new Error(`DIRECTORY_LOADER_REQUIRES_ROOT: ${pluginSubdirectory}`)
-  }
-}
-
-export async function snapshotFromDirectory(
-  root: string,
-  pluginSubdirectory: string
-): Promise<Snapshot> {
-  const directory = resolve(root, pluginSubdirectory)
-  const files = new Map<string, Uint8Array>()
-  const symlinks: string[] = []
-  const rootStat = await fs.lstat(directory)
-  if (rootStat.isSymbolicLink()) return { files, symlinks: [pluginSubdirectory || '.'] }
-  await walk(directory, directory, files, symlinks)
-  return { files, symlinks }
-}
-
-async function walk(
-  root: string,
-  current: string,
-  files: Map<string, Uint8Array>,
-  symlinks: string[]
-): Promise<void> {
-  for (const entry of await fs.readdir(current, { withFileTypes: true })) {
-    const absolute = join(current, entry.name)
-    const relativePath = safeRelativePath(relative(root, absolute), 'DIRECTORY_PATH_INVALID')
-    if (entry.isSymbolicLink()) {
-      symlinks.push(relativePath)
-      continue
-    }
-    if (entry.isDirectory()) await walk(root, absolute, files, symlinks)
-    else if (entry.isFile()) files.set(relativePath, await fs.readFile(absolute))
-  }
-}
-
-function sortArtifactKeys(value: unknown): unknown {
-  if (Array.isArray(value)) return value.map(sortArtifactKeys)
-  if (value !== null && typeof value === 'object')
-    return Object.fromEntries(
-      Object.keys(value as Record<string, unknown>)
-        .toSorted()
-        .map((key) => [key, sortArtifactKeys((value as Record<string, unknown>)[key])])
-    )
-  return value
-}
-
-function json(value: unknown): string {
-  return `${JSON.stringify(sortArtifactKeys(value), null, 2)}\n`
-}
-
-function trimSlugEdges(value: string): string {
-  let start = 0
-  let end = value.length
-  while (start < end && value[start] === '-') start += 1
-  while (end > start && value[end - 1] === '-') end -= 1
-  return value.slice(start, end)
-}
-
-function slug(value: string): string {
-  const result =
-    trimSlugEdges(
-      value
-        .trim()
-        .toLocaleLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-    ).slice(0, 128) || 'unknown'
-  return result.length < 2 ? `${result}-plugin` : result
-}
-
-function stringValue(input: unknown): string | undefined {
-  return typeof input === 'string' && input.trim() ? input.trim() : undefined
-}
-
-function isString(input: unknown): input is string {
-  return typeof input === 'string' && input.trim().length > 0
-}
-
-function arrayValue(input: unknown): unknown[] {
-  return Array.isArray(input) ? input : []
-}
+export {
+  catalogFingerprint,
+  publishCatalog,
+  withCatalogRead,
+  type CatalogCoordinationOptions,
+  type PublicationStep,
+  type PublishOptions,
+} from './catalog-store.js'
+export {
+  createArtifacts,
+  iconAssets,
+  writeArtifacts,
+  type ConsumerIndexOptions,
+  type GeneratedArtifacts,
+} from './artifacts.js'
+export { writeFileAtomically } from './fs-atomic.js'
+export type { PublishedAsset } from './integrity-manifest.js'
+export { buildCatalog } from './build.js'
+export { classifyCapabilities, createCompatibility } from './capabilities.js'
+export { byteDigest, canonicalJson, digest, sourceDigest as bytesDigest } from './digest.js'
+export { CATALOG_CONTRACT_VERSION, type ReleaseTransform } from './plugin-release.js'
+export type { PluginSkipReasonCode, SkippedPlugin } from './plugin-skips.js'
+export type { CatalogPolicy } from './policy.js'
+export {
+  DirectorySnapshotLoader,
+  FixtureSnapshotLoader,
+  NetworkSnapshotLoader,
+  readArchiveFiles,
+  snapshotFromDirectory,
+  type Snapshot,
+  type SnapshotLoader,
+} from './snapshots.js'
+export type { PluginSourcePin, ResolvedSource } from './source-resolution.js'
+export { synchronize, type ChangeReport, type SyncInput, type SyncResult } from './synchronize.js'
+export {
+  normalizeCategory,
+  orderLeadingPlugins,
+  productGroupingKey,
+  stablePluginId,
+  stableReleaseId,
+  type CategoryMap,
+  type ProductAliases,
+} from './taxonomy.js'
+export {
+  createSiteIconFetcher,
+  fetchUpstreamBytes,
+  rawContentUrl,
+  SITE_FETCH_TIMEOUT_MS,
+  upstreamRequestHeaders,
+} from './upstream.js'
+export {
+  verifyArtifacts,
+  verifyCatalogReferences,
+  verifyConsumerIndex,
+  verifyShardArtifact,
+  type ConsumerIndexVerification,
+  type ShardArtifact,
+} from './verify-artifacts.js'