@adea-ai/plugins 3.0.10 → 4.0.1

package/src/index.ts

@@ -1,10 +1,12 @@
 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 { basename, join, relative, resolve } from 'node:path'
 import { Readable } from 'node:stream'
+import { setTimeout as sleep } from 'node:timers/promises'
 import { createGunzip } from 'node:zlib'
 import { extract } from 'tar-stream'
+import { publishCatalog, type PublishOptions } from './catalog-store.js'
 import {
   CatalogSchema,
   type Catalog,
@@ -59,6 +61,18 @@ import {
 } from './site-icons.js'
 import { normalizeDisplayName } from './display-name.js'
 import { immutableAssetUrl } from './publication.js'
+import { sourceDigest as bytesDigest } from './source-digest.js'
+
+export { bytesDigest }
+export {
+  catalogFingerprint,
+  publishCatalog,
+  withCatalogRead,
+  writeFileAtomically,
+  type CatalogCoordinationOptions,
+  type PublicationStep,
+  type PublishOptions,
+} from './catalog-store.js'
 
 /**
  * Marks the catalog format this compiler emits.
@@ -297,17 +311,6 @@ 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)}`
 }
@@ -345,20 +348,26 @@ export async function synchronize(input: SyncInput): Promise<SyncResult> {
     sourceId: config.sourceId,
     commitSha,
   }))
+  const resolvedLock = createSourcesLock(resolved)
   const unchanged =
     input.fromLock === undefined &&
     input.forceRebuild !== true &&
     input.existingLock !== undefined &&
     resolved.length === input.existingLock.sources.length &&
-    resolved.every((source) => {
+    resolvedLock.sources.every((source) => {
       const previous = input.existingLock?.sources.find(
-        (entry) => entry.sourceId === source.config.sourceId
+        (entry) => entry.sourceId === source.sourceId
       )
-      if (!previous) return false
+      if (!previous || sourceLockChanged(previous, source)) return false
+      if (!input.existingCatalog) return true
+      const priorCatalog = input.existingCatalog.sources.find(
+        (entry) => entry.sourceId === source.sourceId
+      )
+      const config = resolved.find((entry) => entry.config.sourceId === source.sourceId)!.config
       return (
-        previous.resolvedCommitSha === source.commitSha &&
-        previous.sourceManifestDigest === source.manifestDigest &&
-        digest(previous.pluginPins) === digest(source.pluginPins)
+        !!priorCatalog &&
+        priorCatalog.displayName === config.displayName &&
+        priorCatalog.trustClassification === config.trustClassification
       )
     })
   if (unchanged) {
@@ -398,7 +407,7 @@ export async function synchronize(input: SyncInput): Promise<SyncResult> {
     ...(input.transformRelease ? { transformRelease: input.transformRelease } : {}),
   })
   const catalog = buildResult.catalog
-  const lock = createSourcesLock(resolved)
+  const lock = resolvedLock
   const artifacts = createArtifacts(orderLeadingPlugins(catalog, input.leading), lock, {
     ...(input.leading ? { leading: input.leading } : {}),
     ...(input.topCount !== undefined ? { topCount: input.topCount } : {}),
@@ -463,6 +472,7 @@ export async function buildCatalog(input: {
       ...(input.productCategories ? { productCategories: input.productCategories } : {}),
       ...(input.leading ? { leading: input.leading } : {}),
       ...(input.productIconOverrides ? { productIconOverrides: input.productIconOverrides } : {}),
+      ...(input.iconAssetsDirectory ? { iconAssetsDirectory: input.iconAssetsDirectory } : {}),
     })
   ).catalog
 }
@@ -988,10 +998,7 @@ async function resolvePluginSource(
     pin?.resolvedCommitSha ??
     spec.sha ??
     (resolveExternalRefs
-      ? await resolveGitRef(
-          spec.repositoryUrl,
-          spec.ref?.startsWith('refs/') ? spec.ref : `refs/heads/${spec.ref ?? 'main'}`
-        )
+      ? await resolveGitRef(spec.repositoryUrl, externalGitRef(spec.ref))
       : source.commitSha)
   return {
     repositoryUrl: canonicalUrl,
@@ -1247,6 +1254,18 @@ function findLicense(
   }
 }
 
+function sourceLockChanged(previous: SourceLockEntry, current: SourceLockEntry): boolean {
+  return (
+    previous.repositoryUrl !== current.repositoryUrl ||
+    previous.defaultBranch !== current.defaultBranch ||
+    previous.manifestPath !== current.manifestPath ||
+    previous.marketplaceDialect !== current.marketplaceDialect ||
+    previous.resolvedCommitSha !== current.resolvedCommitSha ||
+    previous.sourceManifestDigest !== current.sourceManifestDigest ||
+    digest(previous.pluginPins) !== digest(current.pluginPins)
+  )
+}
+
 function createSourcesLock(sources: readonly ResolvedSource[]): SourcesLock {
   const entries: SourceLockEntry[] = sources
     .map((source) => ({
@@ -1485,35 +1504,16 @@ export function iconAssets(index: ConsumerIndex): readonly PublishedAsset[] {
   return [...assets.values()].toSorted((left, right) => left.name.localeCompare(right.name))
 }
 
+/**
+ * Publishes a verified artifact set to `generatedDirectory` under the output's
+ * coordination lock. See `catalog-store.ts` for the publication contract.
+ */
 export async function writeArtifacts(
   generatedDirectory: string,
-  artifacts: GeneratedArtifacts
+  artifacts: GeneratedArtifacts,
+  options: PublishOptions = {}
 ): 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 })
-  }
+  await publishCatalog(generatedDirectory, artifacts as Record<string, string>, options)
 }
 
 export function verifyArtifacts(artifacts: GeneratedArtifacts): void {
@@ -1878,11 +1878,20 @@ function createChangeReport(
             const previous = existingLock.sources.find(
               (candidate) => candidate.sourceId === source.sourceId
             )
+            const priorCatalog = existingCatalog?.sources.find(
+              (entry) => entry.sourceId === source.sourceId
+            )
+            const currentCatalog = catalog.sources.find(
+              (entry) => entry.sourceId === source.sourceId
+            )
             return (
               !previous ||
-              previous?.resolvedCommitSha !== source.resolvedCommitSha ||
-              previous.sourceManifestDigest !== source.sourceManifestDigest ||
-              digest(previous.pluginPins) !== digest(source.pluginPins)
+              sourceLockChanged(previous, source) ||
+              (existingCatalog !== undefined &&
+                (!priorCatalog ||
+                  !currentCatalog ||
+                  priorCatalog.displayName !== currentCatalog.displayName ||
+                  priorCatalog.trustClassification !== currentCatalog.trustClassification))
             )
           })()
         )
@@ -2002,7 +2011,10 @@ async function resolvePluginPins(input: {
 
       const repositoryUrl = canonicalRepositoryUrl(entry.source.repositoryUrl)
       const pluginSubdirectory = entry.source.subdirectory
-      const locked = input.lockedPins?.find((pin) => pin.pluginName === entry.name)
+      // Existing locks describe the prior sync; only explicit replay freezes revisions.
+      const locked = input.fromLock
+        ? input.lockedPins?.find((pin) => pin.pluginName === entry.name)
+        : undefined
       if (input.fromLock && !locked)
         throw new Error(`SOURCE_LOCK_PLUGIN_PIN_MISSING: ${input.config.sourceId}:${entry.name}`)
       if (locked) {
@@ -2018,17 +2030,19 @@ async function resolvePluginPins(input: {
       const resolvedCommitSha =
         entry.source.sha ??
         (input.resolveExternalRefs
-          ? await resolveGitRef(
-              repositoryUrl,
-              entry.source.ref?.startsWith('refs/')
-                ? entry.source.ref
-                : `refs/heads/${entry.source.ref ?? 'main'}`
-            )
+          ? await resolveGitRef(repositoryUrl, externalGitRef(entry.source.ref))
           : input.sourceCommitSha)
       return { pluginName: entry.name, repositoryUrl, pluginSubdirectory, resolvedCommitSha }
     }
   )
-  return pins.toSorted((left, right) => left.pluginName.localeCompare(right.pluginName))
+  return pins.toSorted((left, right) =>
+    left.pluginName < right.pluginName ? -1 : left.pluginName > right.pluginName ? 1 : 0
+  )
+}
+
+function externalGitRef(ref: string | undefined): string {
+  if (ref === undefined) return 'HEAD'
+  return ref.startsWith('refs/') ? ref : `refs/heads/${ref}`
 }
 
 async function mapWithConcurrency<T, U>(
@@ -2061,9 +2075,14 @@ async function readFixtureManifest(
 }
 
 async function resolveGitRef(repositoryUrl: string, ref: string): Promise<string> {
-  const result = spawn('git', ['ls-remote', canonicalRepositoryUrl(repositoryUrl), ref], {
-    stdio: ['ignore', 'pipe', 'pipe'],
-  })
+  const peeled = ref.startsWith('refs/tags/') && !ref.endsWith('^{}') ? `${ref}^{}` : undefined
+  const result = spawn(
+    'git',
+    ['ls-remote', canonicalRepositoryUrl(repositoryUrl), ref, ...(peeled ? [peeled] : [])],
+    {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }
+  )
   const [stdout, stderr, exitCode] = await Promise.all([
     new Promise<string>((resolveOutput, reject) => {
       const chunks: Buffer[] = []
@@ -2084,7 +2103,13 @@ async function resolveGitRef(repositoryUrl: string, ref: string): Promise<string
   ])
   if (exitCode !== 0)
     throw new Error(`GIT_REF_LOOKUP_FAILED: ${repositoryUrl}:${ref}:${stderr.trim()}`)
-  const sha = stdout.trim().split(/\s+/)[0]
+  const rows = stdout
+    .trim()
+    .split('\n')
+    .map((line) => line.split(/\s+/))
+  const sha =
+    (peeled && rows.find((row) => row[1] === peeled)?.[0]) ??
+    rows.find((row) => row[1] === ref)?.[0]
   if (!sha || !/^[a-f0-9]{40}$/.test(sha))
     throw new Error(`GIT_REF_NOT_FOUND: ${repositoryUrl}:${ref}`)
   return sha
@@ -2111,7 +2136,8 @@ function rawUrl(repositoryUrl: string, commitSha: string, path: string): string
 }
 
 async function fetchText(url: string): Promise<string> {
-  const response = await fetch(url, { headers: upstreamRequestHeaders(url) })
+  // Manifest requests use the same bounded retry policy as the tree and archive.
+  const response = await fetchUpstream(url, { headers: upstreamRequestHeaders(url) })
   if (!response.ok) throw new Error(`HTTP_FETCH_FAILED: ${response.status}:${url}`)
   return response.text()
 }
@@ -2192,10 +2218,6 @@ const UPSTREAM_WEATHER_SKIP_CODES: ReadonlySet<PluginSkipReasonCode> = new Set([
   '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) {
@@ -2230,8 +2252,8 @@ async function fetchUpstream(url: string, init: RequestInit): Promise<Response>
     try {
       response = await fetch(url, init)
     } catch (error) {
-      if (attempt >= UPSTREAM_FETCH_MAX_ATTEMPTS - 1) throw error
-      await sleep(upstreamRetryDelayMs(attempt))
+      if (init.signal?.aborted || attempt >= UPSTREAM_FETCH_MAX_ATTEMPTS - 1) throw error
+      await sleep(upstreamRetryDelayMs(attempt), undefined, { signal: init.signal ?? undefined })
       attempt += 1
       continue
     }
@@ -2241,7 +2263,10 @@ async function fetchUpstream(url: string, init: RequestInit): Promise<Response>
       attempt >= UPSTREAM_FETCH_MAX_ATTEMPTS - 1
     )
       return response
-    await sleep(upstreamRetryDelayMs(attempt, response))
+    await response.body?.cancel().catch(() => {})
+    await sleep(upstreamRetryDelayMs(attempt, response), undefined, {
+      signal: init.signal ?? undefined,
+    })
     attempt += 1
   }
 }
@@ -2343,8 +2368,8 @@ export async function readArchiveFiles(
 
 export class NetworkSnapshotLoader implements SnapshotLoader {
   readonly #policy: CatalogPolicy
-  readonly #trees = new Map<string, readonly TreeEntry[]>()
-  readonly #archives = new Map<string, ReadonlyMap<string, Uint8Array>>()
+  readonly #trees = new Map<string, Promise<readonly TreeEntry[]>>()
+  readonly #archives = new Map<string, Promise<ReadonlyMap<string, Uint8Array>>>()
 
   constructor(policy: CatalogPolicy) {
     this.#policy = policy
@@ -2361,22 +2386,28 @@ export class NetworkSnapshotLoader implements SnapshotLoader {
     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),
+    let pendingTree = this.#trees.get(key)
+    if (!pendingTree) {
+      pendingTree = (async () => {
+        const treeUrl = `https://api.github.com/repos/${owner}/${repo}/git/trees/${commitSha}?recursive=1`
+        const response = await fetchUpstream(treeUrl, {
+          headers: upstreamRequestHeaders(treeUrl),
+        })
+        if (!response.ok)
+          throw new PluginSafetyError('PLUGIN_SOURCE_UNAVAILABLE', [`${owner}/${repo}`])
+        const payload = (await response.json()) as { truncated?: boolean; tree?: TreeEntry[] }
+        if (payload.truncated) throw new Error(`GIT_TREE_TRUNCATED: ${owner}/${repo}@${commitSha}`)
+        return (payload.tree ?? []).map((entry) => ({
+          ...entry,
+          path: safeRelativePath(entry.path, 'TREE_PATH_INVALID'),
+        }))
+      })().catch((error: unknown) => {
+        this.#trees.delete(key)
+        throw error
       })
-      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)
+      this.#trees.set(key, pendingTree)
     }
+    const tree = await pendingTree
     const prefix = pluginSubdirectory ? `${safeRelativePath(pluginSubdirectory)}/` : ''
     const submodules = tree.filter(
       (entry) =>
@@ -2428,12 +2459,18 @@ export class NetworkSnapshotLoader implements SnapshotLoader {
   ): 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
+    const pending = (async () => {
+      const url = `https://api.github.com/repos/${owner}/${repo}/tarball/${commitSha}`
+      const response = await fetchUpstream(url, { headers: upstreamRequestHeaders(url) })
+      if (!response.ok)
+        throw new PluginSafetyError('PLUGIN_SOURCE_UNAVAILABLE', [`${owner}/${repo}`])
+      return readArchiveFiles(new Uint8Array(await response.arrayBuffer()), this.#policy)
+    })().catch((error: unknown) => {
+      this.#archives.delete(key)
+      throw error
+    })
+    this.#archives.set(key, pending)
+    return pending
   }
 }
 

package/src/manifest-retry.test.ts

@@ -0,0 +1,49 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { expect, test } from 'bun:test'
+import { FixtureSnapshotLoader, synchronize } from './index.js'
+import { withPortableFixture } from '../test-support/portable-fixture.js'
+
+test('retries transient marketplace manifest responses while preserving permanent failures', () =>
+  withPortableFixture(async (input, root) => {
+    const initial = await synchronize(input)
+    const manifest = await readFile(join(root, 'fixtures/source/marketplace.json'), 'utf8')
+    const realFetch = globalThis.fetch
+    let calls = 0
+    try {
+      globalThis.fetch = (async () => {
+        calls++
+        if (calls < 3)
+          return new Response('temporarily unavailable', {
+            status: 503,
+            headers: { 'retry-after': '0' },
+          })
+        return new Response(manifest, { status: 200 })
+      }) as unknown as typeof fetch
+      const options = {
+        ...input,
+        mode: 'live' as const,
+        fromLock: initial.lock!,
+        snapshotLoader: new FixtureSnapshotLoader(input.fixtureRoot!, input.sources),
+      }
+      const recovered = await synchronize(options)
+      expect(recovered.catalog?.catalogId).toBe(initial.catalog?.catalogId)
+      expect(calls).toBe(3)
+      calls = 0
+      globalThis.fetch = (async () => {
+        calls++
+        return new Response('not found', { status: 404 })
+      }) as unknown as typeof fetch
+      await expect(synchronize(options)).rejects.toThrow('HTTP_FETCH_FAILED: 404')
+      expect(calls).toBe(1)
+      calls = 0
+      globalThis.fetch = (async () => {
+        calls++
+        return new Response('busy', { status: 429, headers: { 'retry-after': '0' } })
+      }) as unknown as typeof fetch
+      await expect(synchronize(options)).rejects.toThrow('HTTP_FETCH_FAILED: 429')
+      expect(calls).toBe(3)
+    } finally {
+      globalThis.fetch = realFetch
+    }
+  }))

package/src/portable-catalog.test.ts

@@ -12,7 +12,7 @@ import {
   PACKAGE_METADATA_KEY,
 } from './portable-catalog.js'
 import { verifyAgentPackage, materializeAgentPackage } from './agent-plugins-catalog.js'
-import { createCatalogInstallationPlan, createInstallationPlan } from './agent-plugins-harness.js'
+import { createCatalogInstallationPlan, createInstallationPlan } from './harness.js'
 import type { HarnessProfile } from './agent-plugins-schema.js'
 import { snapshotFromDirectory } from './index.js'
 import {
@@ -351,7 +351,7 @@ it('refuses a malformed provenance descriptor with one typed line naming the plu
   }))
 
 const CONSUMER_SCRIPT = `import { readFileSync } from 'node:fs'
-import { createCatalogInstallationPlan } from '@adea-ai/plugins/agent-plugins/harness'
+import { createCatalogInstallationPlan } from '@adea-ai/plugins/harness'
 import { synchronizePortable } from '@adea-ai/plugins/portable-catalog'
 import { digest } from '@adea-ai/plugins'
 const request = JSON.parse(readFileSync(process.argv[2], 'utf8'))
@@ -377,7 +377,7 @@ try {
       ok: true,
       plan,
       catalogId: result.catalog.catalogId,
-      resolvedHarness: import.meta.resolve('@adea-ai/plugins/agent-plugins/harness'),
+      resolvedHarness: import.meta.resolve('@adea-ai/plugins/harness'),
       resolvedCatalog: import.meta.resolve('@adea-ai/plugins/portable-catalog'),
     })
   )
@@ -475,7 +475,7 @@ it('keeps the packed consumer inside the packed artifact and its own dependencie
     // The packed artifact was built from the CURRENT source: a stale build
     // would still carry the sentinel the rebuild removes.
     assert.equal(consumer.builtFromCurrentSource, true)
-    assert.equal(existsSync(join(consumer.packedRoot, 'dist', 'agent-plugins-harness.js')), true)
+    assert.equal(existsSync(join(consumer.packedRoot, 'dist', 'harness.js')), true)
     // Every copied dependency really resolves INSIDE the consumer: the
     // workspace installs them as links into the package manager's store, so
     // a copy that kept the link would resolve outside the consumer.
@@ -487,7 +487,10 @@ it('keeps the packed consumer inside the packed artifact and its own dependencie
     // dependencies, and never the whole workspace.
     const packedManifest = JSON.parse(
       await readFile(join(consumer.packedRoot, 'package.json'), 'utf8')
-    ) as { dependencies?: Record<string, string> }
+    ) as { dependencies?: Record<string, string>; exports: Record<string, unknown> }
+    assert.ok(packedManifest.exports['./harness'])
+    assert.equal(packedManifest.exports['./agent-plugins/harness'], undefined)
+    assert.equal(existsSync(join(consumer.packedRoot, 'dist', 'agent-plugins-harness.js')), false)
     const declared = Object.keys(packedManifest.dependencies ?? {})
     for (const name of declared) assert.ok(consumer.linkedDependencies.includes(name))
     const installed = await readdir(join(consumer.consumerRoot, 'node_modules'))

package/src/publication.ts

@@ -9,9 +9,9 @@
  * 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
+ * where `catalogId` is the canonical digest of the catalog itself. The
+ * publisher must reject replacement of existing snapshot bytes, and
+ * `raw.githubusercontent.com` serves the branch with permissive
  * CORS so a browser can fetch it directly.
  */
 
@@ -63,11 +63,9 @@ export interface StagedAssetAudit {
 /**
  * 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.
+ * This checks that the declared bytes exist here at all. Publication must
+ * separately compare the complete staged snapshot with any existing snapshot:
+ * companion artifacts can differ without changing the catalog identity.
  */
 export function auditStagedAssets(input: {
   readonly declared: readonly DeclaredAsset[]
@@ -95,9 +93,8 @@ export interface PublicationPlan {
 /**
  * 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.
+ * A catalog identity names the catalog content. The publisher must also guard
+ * the snapshot path against changes to companion artifacts under the same ID.
  */
 export function catalogIdSuffix(catalogId: string): string {
   const match = /^catalog:([a-f0-9]{64})$/.exec(catalogId)

package/src/schema.ts

@@ -248,45 +248,6 @@ export const SourcesLockSchema = z
   })
   .strict()
 
-export const MaterializationPlanSchema = z
-  .object({
-    planVersion: z.literal(1),
-    pluginId: PluginSchema.shape.pluginId,
-    releaseId: PluginReleaseSchema.shape.releaseId,
-    harness: HarnessSchema,
-    source: z
-      .object({
-        repositoryUrl: z.string().url(),
-        commitSha: ShaSchema,
-        pluginSubdirectory: z.string().min(1),
-        contentDigest: DigestSchema,
-      })
-      .strict(),
-    targetLayout: z
-      .object({
-        root: z.string().min(1),
-        notes: z.array(z.string().min(1)).max(32),
-      })
-      .strict(),
-    files: z
-      .array(
-        z
-          .object({
-            sourcePath: z.string().min(1),
-            targetPath: z.string().min(1),
-            action: z.enum(['copy', 'translate', 'ignore', 'unsupported']),
-            reason: z.string().min(1).max(500),
-          })
-          .strict()
-      )
-      .max(4096),
-    configuration: JsonObjectSchema,
-    requiredConnectors: z.array(z.string().min(1)).max(128),
-    requiredCredentials: z.array(z.string().min(1)).max(128),
-    policyConstraints: z.array(z.string().min(1)).max(128),
-  })
-  .strict()
-
 export type CatalogSource = z.output<typeof CatalogSourceSchema>
 export type Capability = z.output<typeof CapabilitySchema>
 export type HarnessCompatibility = z.output<typeof HarnessCompatibilitySchema>
@@ -298,7 +259,6 @@ export type Plugin = z.output<typeof PluginSchema>
 export type Catalog = z.output<typeof CatalogSchema>
 export type SourceLockEntry = z.output<typeof SourceLockEntrySchema>
 export type SourcesLock = z.output<typeof SourcesLockSchema>
-export type MaterializationPlan = z.output<typeof MaterializationPlanSchema>
 
 export function parseCatalog(input: unknown): Catalog {
   return CatalogSchema.parse(input)