@adea-ai/plugins 4.0.1 → 4.0.6

package/src/consumer-index.test.ts

@@ -101,7 +101,7 @@ describe('product placement', () => {
           categories: ['productivity'],
         }),
       ]),
-      preference,
+      productPreference: preference,
     })
     expect(index.counts).toEqual({ plugins: 2, products: 1, redundantPlugins: 1 })
     expect(index.products['google-calendar']).toMatchObject({
@@ -121,7 +121,7 @@ describe('product placement', () => {
       plugin({ sourceId: 'claude-official', name: 'slack', categories: ['productivity'] }),
       plugin({ sourceId: 'openai-official', name: 'slack', categories: ['communication'] }),
     ])
-    const index = buildConsumerIndex({ catalog: base, preference })
+    const index = buildConsumerIndex({ catalog: base, productPreference: preference })
     // Sources disagree about where Slack belongs; the product belongs in both,
     // while the canonical variant still decides identity.
     expect(index.products.slack!.categories).toEqual(['communication', 'productivity'])
@@ -156,7 +156,7 @@ describe('product placement', () => {
         { ...first, currentReleaseId: 'release:same' },
         { ...second, currentReleaseId: 'release:same' },
       ]),
-      preference,
+      productPreference: preference,
     })
     expect(identical.products.atlan!.variantsIdentical).toBe(true)
   })
@@ -172,7 +172,7 @@ describe('product placement', () => {
           releaseRepositoryUrl: 'https://github.com/slackapi/slack-mcp-plugin',
         }),
       ]),
-      preference,
+      productPreference: preference,
     })
     expect(index.products.slack!.pluginId).toBe('plugin:openai-official:slack')
   })
@@ -196,7 +196,10 @@ describe('product placement', () => {
       resolvedRepositoryUrl: 'https://github.com/openai-official/marketplace',
     }
     const vendorNow = { ...candidate, availableReleases: [oldWrapper, current] }
-    const vendorIndex = buildConsumerIndex({ catalog: catalog([wrapper, vendorNow]), preference })
+    const vendorIndex = buildConsumerIndex({
+      catalog: catalog([wrapper, vendorNow]),
+      productPreference: preference,
+    })
     expect(vendorIndex.products.slack!.pluginId).toBe(candidate.pluginId)
     expect(vendorIndex.products.slack!.release.releaseId).toBe(current.releaseId)
 
@@ -206,7 +209,10 @@ describe('product placement', () => {
     }
     const oldVendor = { ...current, releaseId: 'release:old-vendor' }
     const wrapperNow = { ...candidate, availableReleases: [oldVendor, currentWrapper] }
-    const wrapperIndex = buildConsumerIndex({ catalog: catalog([wrapper, wrapperNow]), preference })
+    const wrapperIndex = buildConsumerIndex({
+      catalog: catalog([wrapper, wrapperNow]),
+      productPreference: preference,
+    })
     expect(wrapperIndex.products.slack!.pluginId).toBe(wrapper.pluginId)
   })
 
@@ -216,7 +222,7 @@ describe('product placement', () => {
         plugin({ sourceId: 'openai-official', name: 'github', categories: ['developer-tools'] }),
         plugin({ sourceId: 'claude-official', name: 'github', categories: ['developer-tools'] }),
       ]),
-      preference,
+      productPreference: preference,
     })
     expect(index.products.github!.pluginId).toBe('plugin:claude-official:github')
   })
@@ -227,7 +233,7 @@ describe('product placement', () => {
         plugin({ sourceId: 'claude-official', name: 'github', categories: ['developer-tools'] }),
         plugin({ sourceId: 'cursor-official', name: 'github', categories: ['developer-tools'] }),
       ]),
-      preference: {
+      productPreference: {
         ...preference,
         canonicalOverrides: { github: 'plugin:cursor-official:github' },
       },
@@ -246,7 +252,7 @@ describe('product placement', () => {
           displayName: 'Figma',
         }),
       ]),
-      preference,
+      productPreference: preference,
     })
     expect(index.products.figma!.displayName).toBe('Figma')
     expect(index.products.figma!.pluginId).toBe('plugin:claude-official:figma')
@@ -257,7 +263,7 @@ describe('product placement', () => {
       catalog: catalog([
         plugin({ sourceId: 'unlisted-source', name: 'tool', categories: ['developer-tools'] }),
       ]),
-      preference,
+      productPreference: preference,
     })
     expect(index.products.tool!.pluginId).toBe('plugin:unlisted-source:tool')
   })
@@ -273,7 +279,7 @@ describe('category shelves', () => {
           plugin({ sourceId: 'claude-official', name, categories: ['productivity'] })
         )
       ),
-      preference,
+      productPreference: preference,
     }
     expect(buildConsumerIndex({ ...input, topCount: 0 }).categories[0]!.topProductKeys).toEqual([])
     for (const topCount of [
@@ -300,7 +306,7 @@ describe('category shelves', () => {
       ),
       leading: { productivity: ['zeta', 'gamma'] },
       topCount: 4,
-      preference,
+      productPreference: preference,
     })
     const category = index.categories[0]!
     expect(category.productKeys).toEqual([
@@ -328,7 +334,7 @@ describe('category shelves', () => {
         }),
       ]),
       leading: { 'education-research': ['teaching'] },
-      preference,
+      productPreference: preference,
     })
     expect(
       index.categories.find((item) => item.category === 'developer-tools')!.topProductKeys
@@ -354,7 +360,7 @@ describe('category shelves', () => {
         security: ['nightvision', 'no-such-plugin'],
         'unknown-category': ['anything'],
       },
-      preference,
+      productPreference: preference,
     })
     expect(index.diagnostics).toEqual([
       { category: 'developer-tools', name: 'getsentry', reason: 'PRODUCT_NOT_FOUND' },
@@ -393,7 +399,7 @@ describe('category shelves', () => {
       const index = buildConsumerIndex({
         catalog: catalog(entries),
         leading: { tools: ['shared', 'renamed', 'present'] },
-        preference,
+        productPreference: preference,
       })
       expect(index.diagnostics).toEqual([
         { category: 'tools', name: 'renamed', reason: 'PRODUCT_NOT_IN_CATEGORY' },
@@ -425,7 +431,7 @@ describe('category shelves', () => {
       const index = buildConsumerIndex({
         catalog: catalog(entries),
         leading: { tools: ['named'] },
-        preference,
+        productPreference: preference,
       })
       expect(index.diagnostics).toEqual([])
       expect(index.categories.find((item) => item.category === 'tools')!.topProductKeys[0]).toBe(
@@ -441,12 +447,12 @@ describe('category shelves', () => {
     const first = buildConsumerIndex({
       catalog: catalog(forward),
       leading: { productivity: ['gamma'] },
-      preference,
+      productPreference: preference,
     })
     const second = buildConsumerIndex({
       catalog: catalog(forward.toReversed()),
       leading: { productivity: ['gamma'] },
-      preference,
+      productPreference: preference,
     })
     expect(JSON.stringify(first)).toBe(JSON.stringify(second))
   })
@@ -527,7 +533,7 @@ describe('consumer index verification', () => {
     const index = buildConsumerIndex({
       catalog: base,
       leading: { productivity: ['b'] },
-      preference,
+      productPreference: preference,
     })
     const result = verifyConsumerIndex(JSON.stringify(index), base)
     expect(result.hasConsumerIndex).toBe(true)
@@ -554,7 +560,7 @@ describe('consumer index verification', () => {
 
   test('rejects a category list that names a plugin outside the catalog', () => {
     const base = catalog(plugins)
-    const index = buildConsumerIndex({ catalog: base, preference })
+    const index = buildConsumerIndex({ catalog: base, productPreference: preference })
     const tampered = {
       ...index,
       categories: index.categories.map((category) => ({
@@ -575,7 +581,7 @@ describe('consumer index verification', () => {
         categories: ['productivity', 'communication'],
       }),
     ])
-    const index = buildConsumerIndex({ catalog: base, preference })
+    const index = buildConsumerIndex({ catalog: base, productPreference: preference })
     const tampered = {
       ...index,
       categories: index.categories.map((category) => ({

package/src/consumer-index.ts

@@ -1,4 +1,5 @@
 import type { Catalog, Plugin, PluginRelease } from './schema.js'
+import { PACKAGE_METADATA_KEY } from './agent-plugins-schema.js'
 import { iconAssetName, type IconContentType } from './icons.js'
 import { immutableAssetUrl } from './publication.js'
 
@@ -60,7 +61,7 @@ export function parseProductPreference(input: unknown): ProductPreference {
 export interface ProductIcon {
   /** `content` is the vendor's own plugin file; `favicon` is the product site's. */
   readonly kind: 'content' | 'favicon'
-  /** Release asset name; fetch it from the release for this `catalogId`. */
+  /** Content-addressed asset name, published beside the catalog's artifacts. */
   readonly asset: string
   /**
    * Absolute, immutable URL for the asset, present when the build knows where
@@ -111,29 +112,6 @@ export interface ConsumerRelease {
   readonly packageDigest?: string
 }
 
-/** One installable product, resolved from every source variant that publishes it. */ /**
- * The install-relevant facts of the release a product installs.
- *
- * A browsing client shows a plugin, then plans an install from it: the digest it
- * must pin, the connectors and credentials setup will ask for, and the
- * capabilities the harness has to negotiate. Carrying them here means the grid
- * needs no second artifact.
- */
-export interface ConsumerRelease {
-  readonly releaseId: string
-  readonly canonicalContentDigest: string
-  readonly contentResolution: string
-  readonly capabilities: readonly { readonly type: string; readonly name: string }[]
-  readonly requiredConnectors: readonly string[]
-  readonly requiredCredentials: readonly string[]
-  /** Commit the release was resolved from, for audit and update state. */
-  readonly sourceRevision: string
-  readonly upstreamVersion?: string
-  /** Canonical package status, when the release carries one. */
-  readonly packageStatus?: string
-  readonly packageDigest?: string
-}
-
 /** One installable product, resolved from every source variant that publishes it. */
 export interface ConsumerProduct {
   readonly productKey: string
@@ -319,7 +297,9 @@ function nestedString(value: unknown, key: string): string | undefined {
 
 function describeRelease(plugin: Plugin): ConsumerRelease {
   const release = currentRelease(plugin)!
-  const packages = ((release.releaseMetadata ?? {}) as Record<string, unknown>).agentPlugins
+  const packages = release.releaseMetadata[PACKAGE_METADATA_KEY]
+  const packageStatus = nestedString(packages, 'status')
+  const packageDigest = nestedString(packages, 'packageDigest')
   return {
     releaseId: release.releaseId,
     canonicalContentDigest: release.canonicalContentDigest,
@@ -332,12 +312,8 @@ function describeRelease(plugin: Plugin): ConsumerRelease {
     requiredCredentials: [...release.requiredCredentials],
     sourceRevision: release.resolvedCommitSha,
     ...(release.upstreamVersion ? { upstreamVersion: release.upstreamVersion } : {}),
-    ...(nestedString(packages, 'status')
-      ? { packageStatus: nestedString(packages, 'status')! }
-      : {}),
-    ...(nestedString(packages, 'packageDigest')
-      ? { packageDigest: nestedString(packages, 'packageDigest')! }
-      : {}),
+    ...(packageStatus ? { packageStatus } : {}),
+    ...(packageDigest ? { packageDigest } : {}),
   }
 }
 
@@ -407,16 +383,17 @@ function compactCompatibility(plugin: Plugin): Record<string, string> {
  * stable identifiers.
  */
 export function buildConsumerIndex(input: {
-  readonly catalog: Pick<Catalog, 'plugins' | 'sources'>
+  /** A catalog without its ID yields records with no published asset URLs. */
+  readonly catalog: Pick<Catalog, 'plugins' | 'sources'> & { readonly catalogId?: string }
   readonly leading?: Readonly<Record<string, readonly string[]>>
   readonly topCount?: number
-  readonly preference?: ProductPreference
+  readonly productPreference?: ProductPreference
   /** Where the catalog will be published, so records can carry absolute URLs. */
   readonly publicationRepositoryUrl?: string
   /** Committed asset base a browser can fetch directly; preferred when set. */
   readonly publicationAssetsBaseUrl?: string
 }): ConsumerIndex {
-  const preference = input.preference ?? {
+  const preference = input.productPreference ?? {
     schemaVersion: 1 as const,
     sourcePreference: [...DEFAULT_SOURCE_PREFERENCE],
   }
@@ -432,7 +409,7 @@ export function buildConsumerIndex(input: {
     if (list) list.push(plugin)
     else variantsByProduct.set(plugin.productGroupingKey, [plugin])
   }
-  const catalogId = (input.catalog as { catalogId?: string }).catalogId ?? ''
+  const catalogId = input.catalog.catalogId ?? ''
   const products: Record<string, ConsumerProduct> = {}
   for (const [productKey, variants] of [...variantsByProduct].toSorted((left, right) =>
     left[0].localeCompare(right[0])

package/src/digest.ts

@@ -0,0 +1,55 @@
+import { createHash } from 'node:crypto'
+
+const DIGEST_PREFIX = 'sha256:'
+
+function sha256Hex(data: string | Uint8Array): string {
+  return createHash('sha256').update(data).digest('hex')
+}
+
+/** Ordinal (UTF-16 code unit) order: the same on every machine and locale. */
+export function ordinalCompare(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0
+}
+
+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(',')}}`
+}
+
+/** Digest of a JSON value's canonical form, in the catalog's digest format. */
+export function digest(value: unknown): string {
+  return `${DIGEST_PREFIX}${sha256Hex(canonicalJson(value))}`
+}
+
+/** Digest of one byte buffer (a string is hashed as UTF-8), in the catalog's digest format. */
+export function byteDigest(bytes: string | Uint8Array): string {
+  return `${DIGEST_PREFIX}${sha256Hex(bytes)}`
+}
+
+/** Shared source-byte identity for catalog provenance and canonical package recipes. */
+export function sourceDigest(files: ReadonlyMap<string, Uint8Array>): string {
+  const hash = createHash('sha256')
+  // English matches the compiler runtime; ordinal ties distinguish equivalent Unicode names.
+  for (const [path, bytes] of [...files].toSorted(
+    ([a], [b]) => a.localeCompare(b, 'en') || ordinalCompare(a, b)
+  )) {
+    hash.update(`${path.length}:${path}:${bytes.byteLength}:`)
+    hash.update(bytes)
+  }
+  return `${DIGEST_PREFIX}${hash.digest('hex')}`
+}
+
+/** A content-addressed identifier such as `catalog:<hex>` for a JSON body. */
+export function contentId(prefix: string, body: unknown): string {
+  return `${prefix}:${sha256Hex(canonicalJson(body))}`
+}
+
+/** The hex part of a `sha256:<hex>` digest. */
+export function digestHex(value: string): string {
+  return value.startsWith(DIGEST_PREFIX) ? value.slice(DIGEST_PREFIX.length) : value
+}

package/src/fs-atomic.ts

@@ -0,0 +1,32 @@
+import { randomUUID } from 'node:crypto'
+import { promises as fs } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+
+/** Creates `path`, failing if it exists, and syncs the bytes before returning. */
+export async function writeDurably(path: string, content: string | Uint8Array): Promise<void> {
+  const handle = await fs.open(path, 'wx')
+  try {
+    await handle.writeFile(content)
+    await handle.sync()
+  } finally {
+    await handle.close()
+  }
+}
+
+/**
+ * Writes one file so a reader sees either the old or the new bytes. For
+ * content-addressed assets and the browsing index beside the catalog.
+ */
+export async function writeFileAtomically(
+  path: string,
+  content: string | Uint8Array
+): Promise<void> {
+  const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`)
+  try {
+    await writeDurably(temporary, content)
+    await fs.rename(temporary, path)
+  } catch (error) {
+    await fs.rm(temporary, { force: true })
+    throw error
+  }
+}

package/src/harness.test.ts

@@ -129,34 +129,6 @@ describe('Control Plane installation plan v2', () => {
     assert.equal(plan.compatibility, 'partial')
     assert.ok(plan.disabled.some((item) => item.component === 'hooks'))
   })
-  it('preserves instance data across releases and harnesses but isolates other instances', () => {
-    const first = createInstallationPlan(input())
-    const updatedPkg = packageFixture({ 'CHANGELOG.md': 'A new release.' })
-    const updated = createInstallationPlan({
-      ...input(updatedPkg),
-      releaseId: `release:${'c'.repeat(64)}`,
-      profile: profile({ harness: 'another-harness' }),
-    })
-    assert.equal(first.dataKey, updated.dataKey)
-    assert.notEqual(first.packageKey, updated.packageKey)
-    assert.notEqual(
-      first.dataKey,
-      createInstallationPlan({ ...input(), instanceId: 'workspace-b/user-a' }).dataKey
-    )
-    assert.notEqual(
-      first.dataKey,
-      createInstallationPlan({ ...input(), pluginId: 'plugin:other:issues' }).dataKey
-    )
-  })
-  it('does not reuse a package cache across source commits with potentially different file modes', () => {
-    const original = input()
-    const other = { ...original, source: { ...original.source, commitSha: 'c'.repeat(40) } }
-    assert.notEqual(
-      createInstallationPlan(original).packageKey,
-      createInstallationPlan(other).packageKey
-    )
-    assert.equal(createInstallationPlan(original).dataKey, createInstallationPlan(other).dataKey)
-  })
   it('rejects mismatched source provenance and unversioned capability claims', () => {
     const args = input()
     assert.throws(() =>
@@ -442,7 +414,7 @@ const MATRIX: {
     disabled: ['mcp:api'],
   },
   {
-    name: 'the same package is adopted partially when the caller opts in',
+    name: 'a package missing one native transport is adopted partially on opt-in',
     pkg: 'full',
     profile: 'nativeWithoutHttp',
     allowPartial: true,
@@ -483,7 +455,7 @@ const MATRIX: {
     disabled: ['hooks'],
   },
   {
-    name: 'the same package is adopted partially when the caller opts in',
+    name: 'a package with a non-portable extra is adopted partially on opt-in',
     pkg: 'withHooks',
     profile: 'native',
     allowPartial: true,
@@ -560,10 +532,11 @@ describe('upgrade identity isolation', () => {
     )
 
     // An upgraded package (new bytes) is a different PACKAGE, under the same
-    // instance data: the data is preserved across the upgrade.
+    // instance data: the data is preserved across the upgrade and the harness.
     const upgraded = createInstallationPlan({
       ...input(packageFixture({ 'CHANGELOG.md': 'A new release.' })),
       releaseId: `release:${'c'.repeat(64)}`,
+      profile: profile({ harness: 'another-harness' }),
     })
     assert.notEqual(first.packageKey, upgraded.packageKey)
     assert.equal(first.dataKey, upgraded.dataKey)
@@ -575,7 +548,6 @@ describe('upgrade identity isolation', () => {
     const rereleased = createInstallationPlan({ ...base, releaseId: `release:${'d'.repeat(64)}` })
     assert.equal(first.packageKey, rereleased.packageKey)
     assert.equal(first.dataKey, rereleased.dataKey)
-    assert.notEqual(first.releaseId, rereleased.releaseId)
 
     // A different source commit is a different package identity under the same
     // instance data.

package/src/harness.ts

@@ -9,7 +9,8 @@ import {
   type InstallationPlan,
 } from './agent-plugins-schema.js'
 import type { Catalog } from './schema.js'
-import { verifyPortableCatalog, PACKAGE_METADATA_KEY } from './portable-catalog.js'
+import { PACKAGE_METADATA_KEY } from './agent-plugins-schema.js'
+import { verifyPortableCatalog } from './portable-verify.js'
 import { verifyAgentPackage, validateServer } from './agent-plugins-catalog.js'
 
 export interface InstallationInput {

package/src/icon-mirror.ts

@@ -1,10 +1,11 @@
 import { promises as fs } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { join } from 'node:path'
 import type { Catalog } from './schema.js'
-import { byteDigest, type PublishedAsset } from './index.js'
+import { byteDigest } from './digest.js'
 import { iconAssetName, inspectIconBytes, type IconContentType } from './icons.js'
 import type { ConsumerIndex } from './consumer-index.js'
-import { writeFileAtomically } from './catalog-store.js'
+import { writeFileAtomically } from './fs-atomic.js'
+import { publishedAssetOf, type PublishedAsset } from './integrity-manifest.js'
 
 /**
  * Where an icon's bytes come from, so a mirror needs no tree walk and no
@@ -36,7 +37,7 @@ export type IconSource =
       readonly homepage: string
     }
 
-export interface IconMirrorResult {
+interface IconMirrorResult {
   /** Icons whose verified bytes are present in the assets directory. */
   readonly staged: readonly PublishedAsset[]
   /** Icons that could not be staged, with the reason, never silently dropped. */
@@ -116,78 +117,54 @@ export async function stageIconAssets(input: {
   /** Reads the icon bytes for a source; live fetches raw content, offline reads fixtures. */
   readonly readBytes: (source: IconSource) => Promise<Uint8Array>
 }): Promise<IconMirrorResult> {
-  const staged: PublishedAsset[] = []
+  const staged = new Map<string, PublishedAsset>()
   const skipped = new Map<string, string>()
-  const complete = new Set<string>()
   const skip = (asset: string, reason: string) => {
     if (!skipped.has(asset)) skipped.set(asset, reason)
   }
   await fs.mkdir(input.assetsDirectory, { recursive: true })
   for (const source of input.sources) {
-    if (complete.has(source.asset)) continue
-    const destination = join(input.assetsDirectory, source.asset)
-    const existing = await fs.readFile(destination).catch(() => undefined)
-    if (existing && byteDigest(existing) === source.digest) {
-      staged.push(publishedAssetOf(source))
-      complete.add(source.asset)
-      skipped.delete(source.asset)
-      continue
-    }
-    if (existing) {
+    if (staged.has(source.asset)) continue
+    const existing = await stagedState(input.assetsDirectory, source.asset, source.digest)
+    if (existing === 'conflict') {
       skip(source.asset, 'ASSET_CONFLICT')
       continue
     }
-    let bytes: Uint8Array
-    try {
-      bytes = await input.readBytes(source)
-    } catch (error) {
-      skip(source.asset, `FETCH_FAILED: ${error instanceof Error ? error.message : String(error)}`)
-      continue
-    }
-    const inspected = inspectIconBytes(bytes)
-    if (!('contentType' in inspected)) {
-      skip(source.asset, inspected.rejected)
-      continue
-    }
-    if (inspected.contentType !== source.contentType) {
-      skip(source.asset, 'CONTENT_TYPE_CHANGED')
-      continue
-    }
-    if (byteDigest(bytes) !== source.digest || bytes.byteLength !== source.bytes) {
-      skip(source.asset, 'DIGEST_MISMATCH')
-      continue
+    if (existing === 'absent') {
+      let bytes: Uint8Array
+      try {
+        bytes = await input.readBytes(source)
+      } catch (error) {
+        skip(
+          source.asset,
+          `FETCH_FAILED: ${error instanceof Error ? error.message : String(error)}`
+        )
+        continue
+      }
+      const inspected = inspectIconBytes(bytes)
+      if (!('contentType' in inspected)) {
+        skip(source.asset, inspected.rejected)
+        continue
+      }
+      if (inspected.contentType !== source.contentType) {
+        skip(source.asset, 'CONTENT_TYPE_CHANGED')
+        continue
+      }
+      if (byteDigest(bytes) !== source.digest || bytes.byteLength !== source.bytes) {
+        skip(source.asset, 'DIGEST_MISMATCH')
+        continue
+      }
+      await writeFileAtomically(join(input.assetsDirectory, source.asset), bytes)
     }
-    await fs.mkdir(dirname(destination), { recursive: true })
-    await writeFileAtomically(destination, bytes)
-    staged.push(publishedAssetOf(source))
-    complete.add(source.asset)
+    staged.set(source.asset, publishedAssetOf(source))
     skipped.delete(source.asset)
   }
-  // Distinct assets: two products can share one mark, and the catalog declares
-  // each asset once.
   return {
-    staged: dedupeAssets(staged),
+    staged: [...staged.values()],
     skipped: [...skipped].map(([asset, reason]) => ({ asset, reason })),
   }
 }
 
-function dedupeAssets(assets: readonly PublishedAsset[]): readonly PublishedAsset[] {
-  const unique = new Map<string, PublishedAsset>()
-  for (const asset of assets) unique.set(asset.name, asset)
-  return [...unique.values()]
-}
-
-function publishedAssetOf(source: IconSource): PublishedAsset {
-  return {
-    name: source.asset,
-    digest: source.digest,
-    bytes: source.bytes,
-    contentType: source.contentType,
-    kind: source.kind,
-    origin: source.kind === 'content' ? source.sourcePath : source.url,
-  }
-}
-
 /**
  * Writes one verified icon into the assets directory.
  *
@@ -201,9 +178,25 @@ export async function stageIconBytes(
   asset: string,
   bytes: Uint8Array
 ): Promise<void> {
-  const destination = join(assetsDirectory, asset)
-  const existing = await fs.readFile(destination).catch(() => undefined)
-  if (existing && byteDigest(existing) === byteDigest(bytes)) return
-  await fs.mkdir(dirname(destination), { recursive: true })
-  await writeFileAtomically(destination, bytes)
+  // These bytes are the ones the digest was computed from, so they replace a
+  // differing file rather than fail the build over it.
+  if ((await stagedState(assetsDirectory, asset, byteDigest(bytes))) === 'present') return
+  await fs.mkdir(assetsDirectory, { recursive: true })
+  await writeFileAtomically(join(assetsDirectory, asset), bytes)
+}
+
+/** Whether a content-addressed asset is already staged with the expected bytes. */
+async function stagedState(
+  directory: string,
+  asset: string,
+  digest: string
+): Promise<'absent' | 'present' | 'conflict'> {
+  let existing: Uint8Array
+  try {
+    existing = await fs.readFile(join(directory, asset))
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return 'absent'
+    throw error
+  }
+  return byteDigest(existing) === digest ? 'present' : 'conflict'
 }

package/src/icons.test.ts

@@ -138,10 +138,6 @@ describe('icon asset names', () => {
     expect(iconAssetName(`sha256:${'b'.repeat(64)}`, 'image/svg+xml')).toBe(
       `icon-${'b'.repeat(32)}.svg`
     )
-    // Identical bytes always resolve to the same asset, so caches stay warm.
-    expect(iconAssetName(`sha256:${'c'.repeat(64)}`, 'image/webp')).toBe(
-      iconAssetName(`sha256:${'c'.repeat(64)}`, 'image/webp')
-    )
   })
 
   test('refuses a content type it cannot name', () => {

package/src/icons.ts

@@ -1,3 +1,4 @@
+import { digestHex } from './digest.js'
 /**
  * Compile-time icon resolution.
  *
@@ -209,14 +210,13 @@ const EXTENSION_BY_CONTENT_TYPE: Readonly<Record<IconContentType, string>> = {
 }
 
 /**
- * Content-addressed asset name. Release assets cannot contain `/`, so the
- * digest prefix and extension form one flat name that any release can host.
+ * Content-addressed asset name. Published names are flat (no `/`), so the
+ * digest and extension form one name that is safe as a file and a URL segment.
  */
 export function iconAssetName(digest: string, contentType: IconContentType): string {
   const extension = EXTENSION_BY_CONTENT_TYPE[contentType]
   if (!extension) throw new Error(`ICON_CONTENT_TYPE_UNSUPPORTED: ${contentType}`)
-  const hex = digest.startsWith('sha256:') ? digest.slice('sha256:'.length) : digest
-  return `icon-${hex.slice(0, 32)}.${extension}`
+  return `icon-${digestHex(digest).slice(0, 32)}.${extension}`
 }
 
 /**