@adea-ai/plugins 1.0.0

package/src/index.ts

@@ -0,0 +1,2538 @@
+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 { 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'
+
+/**
+ * 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 bytesDigest(files: ReadonlyMap<string, Uint8Array>): string {
+  const hash = createHash('sha256')
+  for (const [path, bytes] of [...files.entries()].toSorted(([left], [right]) =>
+    left.localeCompare(right)
+  )) {
+    hash.update(`${path.length}:${path}:${bytes.byteLength}:`)
+    hash.update(bytes)
+  }
+  return `sha256:${hash.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 } : {}),
+    })
+  ).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)
+  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.
+ */
+export function verifyShardArtifact(
+  shard: ShardArtifact,
+  content: string | undefined,
+  verification: ConsumerIndexVerification
+): void {
+  if (content === undefined) throw new Error(`SHARD_MISSING: ${shard.name}`)
+  const parsed = JSON.parse(content) as {
+    catalogId?: unknown
+    category?: unknown
+    topCount?: unknown
+    products?: unknown
+  }
+  // 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
+      const locked = input.lockedPins?.find((pin) => pin.pluginName === entry.name)
+      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 sleep(ms: number): Promise<void> {
+  return new Promise((resolveSleep) => setTimeout(resolveSleep, ms))
+}
+
+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 (attempt >= UPSTREAM_FETCH_MAX_ATTEMPTS - 1) throw error
+      await sleep(upstreamRetryDelayMs(attempt))
+      attempt += 1
+      continue
+    }
+    if (
+      response.ok ||
+      !isRetryableUpstreamStatus(response.status, response) ||
+      attempt >= UPSTREAM_FETCH_MAX_ATTEMPTS - 1
+    )
+      return response
+    await sleep(upstreamRetryDelayMs(attempt, response))
+    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.
+ */
+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
+        chunks.push(bytes)
+      })
+      stream.on('error', fail)
+      stream.on('end', () => {
+        try {
+          const bytes = concatChunks(chunks, length)
+          if (bytes.byteLength > policy.maxFileBytes)
+            throw new Error(`PLUGIN_FILE_TOO_LARGE: ${path}`)
+          totalBytes += bytes.byteLength
+          if (totalBytes > MAX_ARCHIVE_BYTES) throw new Error('PLUGIN_SIZE_POLICY: archive')
+          files.set(path, bytes)
+          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, readonly TreeEntry[]>()
+  readonly #archives = new Map<string, 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 tree = this.#trees.get(key)
+    if (!tree) {
+      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}`)
+      tree = (payload.tree ?? []).map((entry) => ({
+        ...entry,
+        path: safeRelativePath(entry.path, 'TREE_PATH_INVALID'),
+      }))
+      this.#trees.set(key, tree)
+    }
+    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 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}`])
+    const files = await readArchiveFiles(new Uint8Array(await response.arrayBuffer()), this.#policy)
+    this.#archives.set(key, files)
+    return files
+  }
+}
+
+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 : []
+}