@adea-ai/plugins 1.0.0

package/src/portable-catalog.test.ts

@@ -0,0 +1,186 @@
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+import { writeFile, mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { synchronize, verifyArtifacts, digest } from './index.js'
+import {
+  synchronizePortable,
+  verifyPortableCatalog,
+  PACKAGE_METADATA_KEY,
+} from './portable-catalog.js'
+import { verifyAgentPackage, materializeAgentPackage } from './agent-plugins-catalog.js'
+import { snapshotFromDirectory } from './index.js'
+import { withPortableFixture } from '../test-support/portable-fixture.js'
+
+it('normalizes a real offline catalog and preserves source/release identity', () =>
+  withPortableFixture(async (input, root) => {
+    const legacy = await synchronize(input)
+    const portable = await synchronizePortable(input)
+    assert.ok(portable.catalog && portable.artifacts && legacy.catalog)
+    verifyArtifacts(portable.artifacts)
+    verifyPortableCatalog(portable.catalog, true)
+    assert.equal(portable.catalog.schemaVersion, 1)
+    const plugin = portable.catalog.plugins[0]!
+    const release = plugin.availableReleases[0]!
+    assert.equal(release.releaseId, legacy.catalog.plugins[0]?.currentReleaseId)
+    assert.equal(
+      release.canonicalContentDigest,
+      legacy.catalog.plugins[0]?.availableReleases[0]?.canonicalContentDigest
+    )
+    assert.equal(plugin.harnessCompatibility['claude-code'].status, 'unknown')
+    const pkg = verifyAgentPackage(release.releaseMetadata[PACKAGE_METADATA_KEY])
+    const snapshot = await snapshotFromDirectory(
+      join(root, 'fixtures/source'),
+      'plugins/review-kit'
+    )
+    assert.ok(
+      materializeAgentPackage(pkg, snapshot.files).has('skills/review/references/checklist.md')
+    )
+  }))
+it('produces deterministic catalog and integrity artifacts', () =>
+  withPortableFixture(async (input) => {
+    assert.deepEqual(
+      (await synchronizePortable(input)).artifacts,
+      (await synchronizePortable(input)).artifacts
+    )
+  }))
+it('migrates unchanged v1 pins once, then returns unchanged for the canonical contract', () =>
+  withPortableFixture(async (input) => {
+    const legacy = await synchronize(input)
+    const migrated = await synchronizePortable({
+      ...input,
+      existingLock: legacy.lock!,
+      existingCatalog: legacy.catalog!,
+    })
+    assert.equal(migrated.changed, true)
+    assert.deepEqual(migrated.lock, legacy.lock)
+    assert.deepEqual(migrated.changeReport.changedSources, [])
+    assert.deepEqual(migrated.changeReport.changedPlugins, ['plugin:test-source:review-kit'])
+    const unchanged = await synchronizePortable({
+      ...input,
+      existingLock: migrated.lock!,
+      existingCatalog: migrated.catalog!,
+    })
+    assert.equal(unchanged.changed, false)
+  }))
+it('never loads plugin content for metadata-only or dry-run', () =>
+  withPortableFixture(async (input) => {
+    for (const flags of [{ metadataOnly: true }, { dryRun: true }]) {
+      const result = await synchronizePortable({
+        ...input,
+        ...flags,
+        snapshotLoader: {
+          async load() {
+            throw new Error('Must not retrieve content')
+          },
+        },
+      })
+      assert.ok(result.catalog)
+      assert.equal(
+        result.catalog.plugins[0]?.availableReleases[0]?.contentResolution,
+        'metadata-only'
+      )
+      assert.equal(
+        result.catalog.plugins[0]?.availableReleases[0]?.releaseMetadata[PACKAGE_METADATA_KEY],
+        undefined
+      )
+      assert.throws(() => verifyPortableCatalog(result.catalog!, true), /COMPLETE_SOURCE_REQUIRED/)
+    }
+  }))
+it('reports nonportable extras while keeping valid skills available', () =>
+  withPortableFixture(async (input, root) => {
+    await mkdir(join(root, 'fixtures/source/plugins/review-kit/hooks'))
+    await writeFile(join(root, 'fixtures/source/plugins/review-kit/hooks/hooks.json'), '{}')
+    const result = await synchronizePortable(input)
+    const pkg = verifyAgentPackage(
+      result.catalog!.plugins[0]!.availableReleases[0]!.releaseMetadata[PACKAGE_METADATA_KEY]
+    )
+    assert.equal(pkg.status, 'partial')
+    assert.equal(pkg.skills.length, 1)
+    assert.ok(pkg.nonPortable.some((item) => item.kind === 'hooks'))
+  }))
+it('rejects metadata tampering before taking the unchanged-source fast path', () =>
+  withPortableFixture(async (input) => {
+    const first = await synchronizePortable(input)
+    const catalog = structuredClone(first.catalog!)
+    catalog.plugins[0]!.description = 'tampered'
+    await assert.rejects(
+      synchronizePortable({ ...input, existingLock: first.lock!, existingCatalog: catalog }),
+      /CATALOG_ID_MISMATCH/
+    )
+  }))
+it('rejects canonical recipes attached to another source digest', () =>
+  withPortableFixture(async (input) => {
+    const result = await synchronizePortable(input)
+    const catalog = structuredClone(result.catalog!)
+    const release = catalog.plugins[0]!.availableReleases[0]!
+    release.canonicalContentDigest = `sha256:${'f'.repeat(64)}`
+    const { catalogId: _oldId, ...body } = catalog
+    catalog.catalogId = `catalog:${digest(body).slice(7)}`
+    assert.throws(() => verifyPortableCatalog(catalog), /PACKAGE_PROVENANCE_MISMATCH/)
+  }))
+
+it('normalizes each fetched snapshot once without a second pass over source bytes', () =>
+  withPortableFixture(async (input, root) => {
+    let reads = 0
+    let transforms = 0
+    const result = await synchronizePortable({
+      ...input,
+      snapshotLoader: {
+        async load(_repository, _commit, subdirectory) {
+          reads += 1
+          return snapshotFromDirectory(join(root, 'fixtures/source'), subdirectory)
+        },
+      },
+      transformRelease(release) {
+        transforms += 1
+        return release
+      },
+    })
+    assert.equal(reads, 1)
+    assert.equal(transforms, 1)
+    assert.ok(result.catalog)
+    verifyPortableCatalog(result.catalog, true)
+  }))
+
+it('does not allow a composed release transform to rewrite immutable source identity', () =>
+  withPortableFixture(async (input) => {
+    await assert.rejects(
+      synchronizePortable({
+        ...input,
+        transformRelease(release) {
+          return { ...release, resolvedCommitSha: 'b'.repeat(40) }
+        },
+      }),
+      /SOURCE_IDENTITY_CHANGED_BY_TRANSFORM/
+    )
+  }))
+
+it('makes the root manifest authoritative even when nested legacy manifests are malformed', () =>
+  withPortableFixture(async (input, root) => {
+    const directory = join(root, 'fixtures/source/plugins/review-kit/examples/.claude-plugin')
+    await mkdir(directory, { recursive: true })
+    await writeFile(join(directory, 'plugin.json'), '{not-a-manifest')
+    const result = await synchronizePortable(input)
+    assert.equal(result.catalog?.plugins.length, 1)
+    assert.equal(result.changeReport.skippedPlugins.length, 0)
+    verifyPortableCatalog(result.catalog!, true)
+  }))
+
+it('advertises where it is published once the publication is known', () =>
+  withPortableFixture(async (input) => {
+    // The default compiler replaces the artifacts the legacy pass produced, so it
+    // must repeat every option it needs: dropping this one silently strips the
+    // brand-mark and browsing-index URLs from a published catalog.
+    const result = await synchronizePortable({
+      ...input,
+      publicationRepositoryUrl: 'https://github.com/adea-ai/plugins',
+    })
+    const navigation = JSON.parse(result.artifacts!['categories.v1.json']) as {
+      catalogIndexUrl?: string
+      brandMarks?: Record<string, string>
+    }
+    assert.match(navigation.catalogIndexUrl ?? '', /\/catalog-assets\/catalogs\/[a-f0-9]{64}\//)
+    // The fixture plugin ships no mark, so the map is present and empty.
+    assert.deepEqual(navigation.brandMarks, {})
+  }))

package/src/portable-catalog.ts

@@ -0,0 +1,203 @@
+import { CatalogSchema, HarnessSchema, type Catalog, type Plugin } from './schema.js'
+import {
+  orderLeadingPlugins,
+  synchronize,
+  createArtifacts,
+  verifyArtifacts,
+  digest,
+  type SyncInput,
+  type SyncResult,
+  type ReleaseTransform,
+} from './index.js'
+import {
+  compileAgentPackage,
+  verifyAgentPackage,
+  NORMALIZER_VERSION,
+} from './agent-plugins-catalog.js'
+import { CATALOG_CONTRACT_VERSION } from './index.js'
+
+export const PACKAGE_METADATA_KEY = 'agentPlugins'
+function currentContract(catalog: Catalog | undefined): boolean {
+  return (
+    !!catalog &&
+    catalog.plugins.every((plugin) =>
+      plugin.availableReleases.every((release) => {
+        const value = release.releaseMetadata[PACKAGE_METADATA_KEY]
+        return (
+          release.contentResolution === 'complete' &&
+          // A release compiled by an earlier catalog format is not current, so a
+          // format change republishes instead of waiting for an upstream commit.
+          release.releaseMetadata.catalogContract === CATALOG_CONTRACT_VERSION &&
+          value !== null &&
+          typeof value === 'object' &&
+          'normalizerVersion' in value &&
+          value.normalizerVersion === NORMALIZER_VERSION
+        )
+      })
+    )
+  )
+}
+function compatibility(
+  pkg: ReturnType<typeof compileAgentPackage>
+): Plugin['harnessCompatibility'] {
+  // Catalog discovery has no running harness. A brand/source marketplace cannot prove compatibility.
+  return Object.fromEntries(
+    HarnessSchema.options.map((harness) => [
+      harness,
+      {
+        status:
+          pkg.status === 'unavailable'
+            ? 'unsupported'
+            : pkg.status === 'partial'
+              ? 'partially-supported'
+              : 'unknown',
+        reasons: [
+          pkg.status === 'unavailable'
+            ? 'No valid canonical package is available.'
+            : 'Agent Plugins core is parsed; negotiate the actual runtime capability profile in a v2 installation plan. Policy approval is separate.',
+        ],
+        responsibleCapabilities: [
+          ...new Set([
+            ...(pkg.skills.length ? ['skill' as const] : []),
+            ...(Object.keys(pkg.mcpServers).length ? ['mcp-server' as const] : []),
+          ]),
+        ],
+      },
+    ])
+  ) as Plugin['harnessCompatibility']
+}
+
+/** Default compiler path: immutable upstream catalog + canonical portable package recipes.
+ * The existing v1 catalog envelope remains stable; the extension is versioned inside
+ * releaseMetadata, which v1 deliberately defines as extensible JSON.
+ */
+export async function synchronizePortable(options: SyncInput): Promise<SyncResult> {
+  if (options.existingCatalog) verifyPortableCatalog(options.existingCatalog)
+  const transformRelease: ReleaseTransform = (original, snapshot, name) => {
+    const release = options.transformRelease?.(original, snapshot, name) ?? original
+    if (
+      release.releaseId !== original.releaseId ||
+      release.canonicalContentDigest !== original.canonicalContentDigest ||
+      release.resolvedRepositoryUrl !== original.resolvedRepositoryUrl ||
+      release.resolvedCommitSha !== original.resolvedCommitSha ||
+      release.pluginSubdirectory !== original.pluginSubdirectory ||
+      release.contentResolution !== original.contentResolution
+    )
+      throw new Error('SOURCE_IDENTITY_CHANGED_BY_TRANSFORM')
+    const pkg = compileAgentPackage({
+      ...snapshot,
+      name,
+      sourceDigest: original.canonicalContentDigest,
+    })
+    return {
+      ...release,
+      releaseMetadata: { ...release.releaseMetadata, [PACKAGE_METADATA_KEY]: pkg },
+    }
+  }
+  // Compile while each upstream snapshot is already in scope. Do not retain all
+  // marketplace file bytes or fetch every package a second time after cataloging.
+  const input = {
+    ...options,
+    metadataOnly: options.metadataOnly === true || options.dryRun === true,
+    transformRelease,
+  }
+  let result = await synchronize(input)
+  if (
+    !result.changed &&
+    !input.metadataOnly &&
+    !currentContract(input.existingCatalog) &&
+    input.existingLock
+  ) {
+    // Replay the already verified pins when the compiler contract changes. Source heads
+    // need not change for a format migration, and dry runs still never publish.
+    result = await synchronize({ ...input, fromLock: input.existingLock })
+  }
+  if (!result.catalog || !result.lock || input.metadataOnly) return result
+  const plugins: Plugin[] = []
+  for (const plugin of result.catalog.plugins) {
+    const releases = plugin.availableReleases
+    const selected = releases.find((release) => release.releaseId === plugin.currentReleaseId)
+    const pkg = selected?.releaseMetadata[PACKAGE_METADATA_KEY]
+    plugins.push({
+      ...plugin,
+      availableReleases: releases,
+      ...(pkg ? { harnessCompatibility: compatibility(verifyAgentPackage(pkg)) } : {}),
+    })
+  }
+  const { catalogId: _oldId, ...old } = CatalogSchema.parse(result.catalog)
+  // Ordering is applied before the catalog ID is computed so the emitted
+  // identifier digests the final plugin order: each category's leading
+  // products head the list.
+  const ordered = orderLeadingPlugins({ ...old, plugins }, options.leading)
+  const catalog = CatalogSchema.parse({
+    ...ordered,
+    catalogId: `catalog:${digest(ordered).slice(7)}`,
+  })
+  verifyPortableCatalog(catalog)
+  const artifacts = createArtifacts(catalog, result.lock, {
+    ...(options.leading ? { leading: options.leading } : {}),
+    ...(options.topCount !== undefined ? { topCount: options.topCount } : {}),
+    ...(options.productPreference ? { productPreference: options.productPreference } : {}),
+    // Without this the shipped artifacts cannot advertise where they are
+    // published, so brand marks and the browsing index lose their URLs. This
+    // path replaces the artifacts the legacy compiler already produced, which is
+    // why it must repeat every option it needs.
+    ...(options.publicationRepositoryUrl
+      ? { publicationRepositoryUrl: options.publicationRepositoryUrl }
+      : {}),
+    ...(options.publicationAssetsBaseUrl
+      ? { publicationAssetsBaseUrl: options.publicationAssetsBaseUrl }
+      : {}),
+    curationDiagnostics: (options.mode ?? 'live') !== 'offline',
+  })
+  verifyArtifacts(artifacts)
+  const changed = catalog.plugins
+    .filter((plugin) => {
+      const prior = input.existingCatalog?.plugins.find((item) => item.pluginId === plugin.pluginId)
+      return prior && digest(prior) !== digest(plugin)
+    })
+    .map((plugin) => plugin.pluginId)
+  return {
+    ...result,
+    catalog,
+    artifacts,
+    changeReport: {
+      ...result.changeReport,
+      changedPlugins: [...new Set([...result.changeReport.changedPlugins, ...changed])].toSorted(),
+    },
+  }
+}
+
+export function verifyPortableCatalog(catalog: Catalog, requirePortable = false): void {
+  const { catalogId, ...body } = CatalogSchema.parse(catalog)
+  if (catalogId !== `catalog:${digest(body).slice(7)}`) throw new Error('CATALOG_ID_MISMATCH')
+  const ids = new Set<string>()
+  for (const plugin of catalog.plugins) {
+    if (ids.has(plugin.pluginId)) throw new Error('DUPLICATE_PLUGIN_ID')
+    ids.add(plugin.pluginId)
+    const releases = new Set(plugin.availableReleases.map((release) => release.releaseId))
+    if (releases.size !== plugin.availableReleases.length || !releases.has(plugin.currentReleaseId))
+      throw new Error('RELEASE_SELECTION_INVALID')
+  }
+  for (const plugin of catalog.plugins)
+    for (const release of plugin.availableReleases) {
+      if (requirePortable && release.contentResolution !== 'complete')
+        throw new Error('COMPLETE_SOURCE_REQUIRED')
+      const descriptor = release.releaseMetadata[PACKAGE_METADATA_KEY]
+      if (descriptor === undefined) {
+        if (requirePortable && release.contentResolution === 'complete')
+          throw new Error(`PORTABLE_RESYNC_REQUIRED: ${plugin.pluginId}`)
+        continue
+      }
+      const pkg = verifyAgentPackage(descriptor)
+      if (
+        release.contentResolution !== 'complete' ||
+        pkg.sourceDigest !== release.canonicalContentDigest
+      )
+        throw new Error(`PACKAGE_PROVENANCE_MISMATCH: ${plugin.pluginId}`)
+      const sourcePaths = new Set(release.fileIndex)
+      for (const file of pkg.files)
+        if (file.action === 'copy' && !sourcePaths.has(file.sourcePath))
+          throw new Error(`PACKAGE_SOURCE_FILE_MISSING: ${plugin.pluginId}`)
+    }
+}

package/src/publication.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  auditStagedAssets,
+  catalogAssetsBaseUrl,
+  catalogIdSuffix,
+  catalogSnapshotBaseUrl,
+  createPublicationPlan,
+  immutableAssetUrl,
+  latestPointerUrl,
+  publishedArtifactNames,
+} from './publication.js'
+
+const repositoryUrl = 'https://github.com/adea-ai/plugins'
+const catalogId = `catalog:${'c'.repeat(64)}`
+const catalogAsset = { name: 'catalog.v1.json', digest: `sha256:${'1'.repeat(64)}`, bytes: 10 }
+
+describe('catalog identity', () => {
+  test('a catalog identity addresses itself by its own digest', () => {
+    expect(catalogIdSuffix(catalogId)).toBe('c'.repeat(64))
+  })
+
+  test('an identity that is not a digest is refused', () => {
+    expect(() => catalogIdSuffix('catalog:not-a-digest')).toThrow('CATALOG_ID_INVALID')
+    expect(() => catalogIdSuffix(`catalog:${'C'.repeat(64)}`)).toThrow('CATALOG_ID_INVALID')
+    expect(() => catalogIdSuffix(`catalog:${'c'.repeat(63)}`)).toThrow('CATALOG_ID_INVALID')
+  })
+})
+
+describe('catalog publication addresses', () => {
+  test('snapshots are content-addressed on the catalog-assets branch', () => {
+    expect(catalogAssetsBaseUrl(repositoryUrl)).toBe(
+      'https://raw.githubusercontent.com/adea-ai/plugins/catalog-assets'
+    )
+    expect(catalogSnapshotBaseUrl(repositoryUrl, catalogId)).toBe(
+      `https://raw.githubusercontent.com/adea-ai/plugins/catalog-assets/catalogs/${'c'.repeat(64)}`
+    )
+  })
+
+  test('the pointer is the only mutable path and it sits at the branch root', () => {
+    expect(latestPointerUrl(repositoryUrl)).toBe(
+      'https://raw.githubusercontent.com/adea-ai/plugins/catalog-assets/catalog-latest.v1.json'
+    )
+  })
+
+  test('a snapshot path is stable for its catalog, so a pinned URL caches forever', () => {
+    const first = immutableAssetUrl(repositoryUrl, catalogId, 'catalog.v1.json')
+    const second = immutableAssetUrl(`${repositoryUrl}.git`, catalogId, 'catalog.v1.json')
+    expect(first).toBe(second)
+    expect(first).toBe(
+      `https://raw.githubusercontent.com/adea-ai/plugins/catalog-assets/catalogs/${'c'.repeat(64)}/catalog.v1.json`
+    )
+  })
+
+  test('a different catalog never addresses the same path', () => {
+    expect(immutableAssetUrl(repositoryUrl, catalogId, 'catalog.v1.json')).not.toBe(
+      immutableAssetUrl(repositoryUrl, `catalog:${'d'.repeat(64)}`, 'catalog.v1.json')
+    )
+  })
+
+  test('an asset name that could escape the snapshot directory is refused', () => {
+    expect(() => immutableAssetUrl(repositoryUrl, catalogId, '../secrets.json')).toThrow(
+      'ASSET_NAME_INVALID'
+    )
+    expect(() => immutableAssetUrl(repositoryUrl, catalogId, 'a/b.json')).toThrow(
+      'ASSET_NAME_INVALID'
+    )
+  })
+
+  test('only a GitHub repository can be addressed', () => {
+    expect(() => catalogAssetsBaseUrl('https://example.com/adea-ai/plugins')).toThrow(
+      'REPOSITORY_URL_UNSUPPORTED'
+    )
+    expect(() => catalogAssetsBaseUrl('not a url')).toThrow('REPOSITORY_URL_INVALID')
+    expect(() => catalogAssetsBaseUrl('https://github.com/adea-ai')).toThrow(
+      'REPOSITORY_URL_INVALID'
+    )
+  })
+
+  test('the plan names the branch paths a publication has to write', () => {
+    const plan = createPublicationPlan({ repositoryUrl, catalogId: `catalog:${'a'.repeat(64)}` })
+    expect(plan.snapshotPath).toBe(`catalogs/${'a'.repeat(64)}`)
+    expect(plan.latestPointerName).toBe('catalog-latest.v1.json')
+    expect(plan.latestPointerUrl).toBe(latestPointerUrl(repositoryUrl))
+    expect(plan.immutableCatalogUrl).toBe(
+      immutableAssetUrl(repositoryUrl, `catalog:${'a'.repeat(64)}`, 'catalog.v1.json')
+    )
+    expect(plan.artifactNames).toEqual(publishedArtifactNames)
+  })
+})
+
+describe('staged asset audit', () => {
+  test('declared bytes this build has are publishable', () => {
+    const audit = auditStagedAssets({ declared: [catalogAsset] })
+    expect(audit.agrees).toBe(true)
+    expect(audit.unstaged).toEqual([])
+    expect(audit.blocked).toBeUndefined()
+  })
+
+  test('a declared asset this build cannot stage is never taken on its word', () => {
+    const audit = auditStagedAssets({
+      declared: [catalogAsset, { name: 'icon-unstaged.png', digest: 'sha256:x', bytes: 5 }],
+      unstaged: ['icon-unstaged.png'],
+    })
+    expect(audit.unstaged).toEqual(['icon-unstaged.png'])
+    expect(audit.agrees).toBe(false)
+    expect(audit.blocked).toContain('no staged bytes')
+    expect(audit.blocked).toContain('mirror-icons')
+  })
+
+  test('the same unstaged name twice is one problem', () => {
+    const audit = auditStagedAssets({
+      declared: [catalogAsset],
+      unstaged: ['icon-unstaged.png', 'icon-unstaged.png'],
+    })
+    expect(audit.unstaged).toEqual(['icon-unstaged.png'])
+  })
+})

package/src/publication.ts

@@ -0,0 +1,171 @@
+/**
+ * Where a published catalog lives, and the URLs that address it.
+ *
+ * The catalog is published to the `catalog-assets` branch rather than to a
+ * GitHub Release. That is what lets the repository's Releases carry a plain
+ * `vX.Y.Z` version and stay readable: GitHub marks exactly one release
+ * "latest", and a content-addressed catalog that has to be discoverable through
+ * `releases/latest/download/…` permanently outbids every versioned release for
+ * that slot, so no version is ever the one a visitor sees first.
+ *
+ * The branch gives each catalog an immutable path — `catalogs/<catalogId>/…`,
+ * where `catalogId` is the canonical digest of the catalog itself — so a
+ * pinned URL is immutable by construction, exactly as a content-addressed
+ * release tag was, and `raw.githubusercontent.com` serves it with permissive
+ * CORS so a browser can fetch it directly.
+ */
+
+export const publishedArtifactNames = [
+  'catalog.v1.json',
+  'catalog-summary.v1.json',
+  'categories.v1.json',
+  'compatibility.v1.json',
+  'integrity.json',
+  'sources.lock.json',
+] as const
+
+export type PublishedArtifactName = (typeof publishedArtifactNames)[number]
+
+/** The branch every catalog snapshot and mirrored brand mark is published to. */
+export const catalogAssetsBranch = 'catalog-assets' as const
+
+/** Directory under the branch holding one immutable snapshot per catalog. */
+export const catalogSnapshotDirectory = 'catalogs' as const
+
+/**
+ * The mutable pointer, byte-identical to the current snapshot's
+ * `catalog.v1.json`. It is the only catalog path that changes after a
+ * publication, so consumers must treat it as a short-TTL cache entry and
+ * resolve everything else from the `catalogId` it names.
+ */
+export const latestPointerName = 'catalog-latest.v1.json' as const
+
+/** One artifact this build declares, with the digest of the bytes it staged. */
+export interface DeclaredAsset {
+  readonly name: string
+  readonly digest: string
+  readonly bytes: number
+}
+
+export interface StagedAssetAudit {
+  /** Declared assets this build has no staged bytes for. */
+  readonly unstaged: readonly string[]
+  /**
+   * Why the snapshot cannot be published, when it cannot. A checkout that
+   * cannot supply the declared bytes cannot publish a snapshot from them
+   * either, and a declaration is not a substitute for them.
+   */
+  readonly blocked?: string
+  /** True when every declared asset has staged bytes behind it. */
+  readonly agrees: boolean
+}
+
+/**
+ * Audits the bytes this build staged against what it declared.
+ *
+ * A content-addressed path removes the comparison the release audit used to
+ * perform: a snapshot published at `catalogs/<catalogId>/` can only hold this
+ * catalog's bytes, because any different build has a different `catalogId` and
+ * therefore a different path. What survives is the check that cannot be
+ * delegated to the path — that the bytes exist here at all.
+ */
+export function auditStagedAssets(input: {
+  readonly declared: readonly DeclaredAsset[]
+  readonly unstaged?: readonly string[]
+}): StagedAssetAudit {
+  const unstaged = [...new Set(input.unstaged ?? [])].toSorted()
+  if (unstaged.length > 0)
+    return {
+      unstaged,
+      blocked: `this checkout has no staged bytes for ${unstaged.length} declared asset(s) (${unstaged.slice(0, 3).join(', ')}${unstaged.length > 3 ? ', …' : ''}); stage them with \`bun run catalog mirror-icons\` or publish from a snapshot that carries them, because a snapshot cannot be checked against a declaration alone`,
+      agrees: false,
+    }
+  return { unstaged: [], agrees: true }
+}
+
+export interface PublicationPlan {
+  /** Branch-relative directory holding this catalog's immutable artifacts. */
+  readonly snapshotPath: string
+  readonly latestPointerName: typeof latestPointerName
+  readonly latestPointerUrl: string
+  readonly immutableCatalogUrl: string
+  readonly artifactNames: readonly PublishedArtifactName[]
+}
+
+/**
+ * The 64-hex digest a `catalog:<hex>` identity is addressed by.
+ *
+ * A catalog identity names its own bytes, so this is also what makes the
+ * snapshot path immutable: any build that produced different content has a
+ * different identity and cannot write over this one.
+ */
+export function catalogIdSuffix(catalogId: string): string {
+  const match = /^catalog:([a-f0-9]{64})$/.exec(catalogId)
+  if (!match) throw new Error(`CATALOG_ID_INVALID: ${catalogId}`)
+  return match[1] as string
+}
+
+/**
+ * Root of the branch that carries mirrored brand marks and the mutable
+ * catalog pointer.
+ */
+export function catalogAssetsBaseUrl(repositoryUrl: string): string {
+  return `https://raw.githubusercontent.com/${repositorySlug(repositoryUrl)}/${catalogAssetsBranch}`
+}
+
+/** Root of one catalog's immutable artifacts, content-addressed by identity. */
+export function catalogSnapshotBaseUrl(repositoryUrl: string, catalogId: string): string {
+  return `${catalogAssetsBaseUrl(repositoryUrl)}/${catalogSnapshotDirectory}/${catalogIdSuffix(catalogId)}`
+}
+
+/** The mutable pointer, re-pointed at the newest catalog on every publication. */
+export function latestPointerUrl(repositoryUrl: string): string {
+  return `${catalogAssetsBaseUrl(repositoryUrl)}/${latestPointerName}`
+}
+
+export function createPublicationPlan(input: {
+  readonly repositoryUrl: string
+  readonly catalogId: string
+}): PublicationPlan {
+  const base = catalogSnapshotBaseUrl(input.repositoryUrl, input.catalogId)
+  return {
+    snapshotPath: `${catalogSnapshotDirectory}/${catalogIdSuffix(input.catalogId)}`,
+    latestPointerName,
+    latestPointerUrl: latestPointerUrl(input.repositoryUrl),
+    immutableCatalogUrl: `${base}/catalog.v1.json`,
+    artifactNames: publishedArtifactNames,
+  }
+}
+
+/**
+ * Immutable URL for one artifact of one catalog.
+ *
+ * The path is derived from the catalog identity, so this URL never changes for
+ * a given catalog and can be cached forever. Deployments that cannot serve the
+ * branch host directly publish the same artifact names behind their own base
+ * and substitute it for `catalogAssetsBaseUrl`.
+ */
+export function immutableAssetUrl(
+  repositoryUrl: string,
+  catalogId: string,
+  assetName: string
+): string {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(assetName))
+    throw new Error(`ASSET_NAME_INVALID: ${assetName}`)
+  return `${catalogSnapshotBaseUrl(repositoryUrl, catalogId)}/${assetName}`
+}
+
+function repositorySlug(repositoryUrl: string): string {
+  let parsed: URL
+  try {
+    parsed = new URL(repositoryUrl)
+  } catch {
+    throw new Error(`REPOSITORY_URL_INVALID: ${repositoryUrl}`)
+  }
+  if (parsed.protocol !== 'https:' || parsed.hostname !== 'github.com')
+    throw new Error(`REPOSITORY_URL_UNSUPPORTED: ${repositoryUrl}`)
+  const path = parsed.pathname.replace(/^\/+|\/+$/g, '').replace(/\.git$/, '')
+  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(path))
+    throw new Error(`REPOSITORY_URL_INVALID: ${repositoryUrl}`)
+  return path
+}