@lesliechan721/aw-plugin-core 0.1.0-beta.7 → 0.1.0-beta.8

package/dist/workspace.js

@@ -4,6 +4,7 @@ import { isDeepStrictEqual } from 'node:util';
 import fs from 'fs-extra';
 import { assertCatalogVersion, assertStrictSemVer, compareStrictSemVer, MARKETPLACE_SOURCE_PATH, SOURCE_MANIFEST_PATH, createMarketplaceManifest, createMarketplaceManifestEntry, normalizeCatalogManifestBase, normalizeCatalogMarketplaceIdentity, normalizeCatalogManifestEntries, normalizeManifestDigestInput, readMarketplaceSourceMeta, readPluginManifest, validatePlatformManifestProjection, } from './manifest-contract.js';
 import { resolveSupportedPlatforms } from './platform-support.js';
+import { createAwPluginRequirementsReceipt, normalizeAwCapabilities, parseAwPluginRequirementsReceipt, } from './aw-capabilities.js';
 import { appendCatalogToPluginReleaseLedger, assertStablePluginVersion, PLUGIN_RELEASE_LEDGER_FILENAME, PLUGIN_RELEASE_LEDGER_SCHEMA_VERSION, resolveBetaPluginVersionOverrides, validatePluginReleaseLedgerAgainstManifest, } from './plugin-release.js';
 export const DEFAULT_CATALOG_WORKSPACE_VERSION = '0.1.0';
 export const DEFAULT_CATALOG_OUTPUT_PATH = path.join('.aw', 'catalog');
@@ -12,6 +13,7 @@ export const DEFAULT_PLUGIN_OUTPUT_PATH = path.join('.aw', 'plugins');
 export const CATALOG_MANIFEST_FILENAME = 'catalog-manifest.json';
 export const GENERATED_OUTPUT_MARKER_FILENAME = '.aw-generated.json';
 export const CATALOG_WORKSPACE_MARKER_FILENAME = '.aw-workspace.json';
+const AW_PLUGIN_REQUIREMENTS_RECEIPT_FILENAME = 'aw-plugin-requirements.json';
 function isInside(root, candidate) {
     const relative = path.relative(root, candidate);
     return relative === '' || (relative !== '..'
@@ -406,7 +408,7 @@ function publishedContentDigest(manifest) {
             owner: manifest.marketplace.owner,
             interface: manifest.marketplace.interface,
         },
-        compatibility: manifest.compatibility,
+        requires: manifest.requires,
         plugins: manifest.entries.map((entry) => ({
             name: entry.name,
             targetVersion: entry.version.replace(/-beta\.[1-9]\d*$/u, ''),
@@ -414,13 +416,54 @@ function publishedContentDigest(manifest) {
         })).sort((left, right) => left.name.localeCompare(right.name)),
     }));
 }
-function sourceIdentity(metadata, plugins) {
-    return sha256(stableStringify({
-        metadata,
-        plugins: [...plugins]
-            .sort((left, right) => left.manifest.name.localeCompare(right.manifest.name))
-            .map((plugin) => plugin.manifest),
-    }));
+const SOURCE_IDENTITY_EXCLUDED_DIRECTORIES = new Set([
+    '.git', '.aw', 'node_modules', 'evals', 'reports',
+]);
+const SOURCE_IDENTITY_EXCLUDED_FILES = new Set([
+    '.DS_Store', 'AGENTS.md', 'CLAUDE.md',
+]);
+async function sourceIdentityRecords(root, relative = '') {
+    const records = [];
+    for (const entry of (await fs.readdir(path.join(root, relative), { withFileTypes: true }))
+        .sort((left, right) => left.name.localeCompare(right.name))) {
+        if (SOURCE_IDENTITY_EXCLUDED_DIRECTORIES.has(entry.name) || SOURCE_IDENTITY_EXCLUDED_FILES.has(entry.name)) {
+            continue;
+        }
+        const child = relative ? path.posix.join(relative, entry.name) : entry.name;
+        const filePath = path.join(root, child);
+        const stat = await fs.lstat(filePath);
+        if (stat.isSymbolicLink())
+            throw new Error(`Catalog source identity does not accept symbolic links: ${filePath}`);
+        if (stat.isDirectory())
+            records.push(...await sourceIdentityRecords(root, child));
+        else if (stat.isFile()) {
+            const mode = (stat.mode & 0o111) === 0 ? '100644' : '100755';
+            records.push(`${child}\0${mode}\0${sha256(await fs.readFile(filePath))}`);
+        }
+        else {
+            throw new Error(`Catalog source identity only accepts regular files and directories: ${filePath}`);
+        }
+    }
+    return records;
+}
+export async function calculateCatalogWorkspaceSourceIdentity(workspace) {
+    const roots = [workspace.metadataPath, ...workspace.plugins.map((plugin) => plugin.rootDir)];
+    const records = [];
+    for (const sourceRoot of roots.sort((left, right) => left.localeCompare(right))) {
+        const relativeRoot = path.relative(workspace.workspaceRoot, sourceRoot).split(path.sep).join('/');
+        const stat = await fs.lstat(sourceRoot);
+        if (stat.isSymbolicLink())
+            throw new Error(`Catalog source identity does not accept symbolic links: ${sourceRoot}`);
+        if (stat.isFile()) {
+            const mode = (stat.mode & 0o111) === 0 ? '100644' : '100755';
+            records.push(`${relativeRoot}\0${mode}\0${sha256(await fs.readFile(sourceRoot))}`);
+        }
+        else if (stat.isDirectory()) {
+            for (const record of await sourceIdentityRecords(sourceRoot))
+                records.push(`${relativeRoot}/${record}`);
+        }
+    }
+    return sha256(records.sort().join('\n'));
 }
 function generatedOutputMarker(options) {
     return {
@@ -451,9 +494,26 @@ async function catalogPathRecord(root, relative, versionNeutral) {
     if (!stat.isFile())
         throw new Error(`Catalog digest path must be a regular file or symlink: ${filePath}.`);
     const manifests = new Set(['.agents-plugin/plugin.json', '.claude-plugin/plugin.json', '.codex-plugin/plugin.json']);
-    const digest = versionNeutral && manifests.has(relative)
-        ? sha256(stableStringify({ ...await fs.readJson(filePath), version: '<plugin-version>' }))
-        : sha256(await fs.readFile(filePath));
+    let digest;
+    if (versionNeutral && manifests.has(relative)) {
+        digest = sha256(stableStringify({
+            ...await fs.readJson(filePath),
+            version: '<plugin-version>',
+        }));
+    }
+    else if (versionNeutral && path.posix.basename(relative) === AW_PLUGIN_REQUIREMENTS_RECEIPT_FILENAME) {
+        const receipt = await fs.readJson(filePath);
+        const plugin = receipt.plugin && typeof receipt.plugin === 'object' && !Array.isArray(receipt.plugin)
+            ? receipt.plugin
+            : {};
+        digest = sha256(stableStringify({
+            ...receipt,
+            plugin: { ...plugin, version: '<plugin-version>' },
+        }));
+    }
+    else {
+        digest = sha256(await fs.readFile(filePath));
+    }
     return { path: relative, kind: 'file', mode: (stat.mode & 0o100) === 0 ? '100644' : '100755', digest };
 }
 async function calculateEntryDigest(root, versionNeutral) {
@@ -461,15 +521,43 @@ async function calculateEntryDigest(root, versionNeutral) {
     return sha256(stableStringify(await Promise.all(files.map((file) => catalogPathRecord(root, file, versionNeutral)))));
 }
 async function expectedCatalogEntry(plugin, pluginRoot) {
+    const bundleManifest = await readRegularJson(path.join(pluginRoot, SOURCE_MANIFEST_PATH), `Catalog plugin ${JSON.stringify(plugin.manifest.name)} bundle manifest`);
     return {
         ...createMarketplaceManifestEntry(plugin),
         version: plugin.manifest.version,
-        compatibility: plugin.manifest.compatibility,
+        dependencies: [...(plugin.manifest.dependencies ?? [])].sort(),
+        requires: {
+            aw: {
+                capabilities: normalizeAwCapabilities(plugin.manifest.requires?.aw.capabilities ?? []),
+            },
+        },
         artifactDigest: await calculateEntryDigest(pluginRoot, false),
-        manifestDigest: sha256(normalizeManifestDigestInput(plugin.manifest)),
+        manifestDigest: sha256(normalizeManifestDigestInput(bundleManifest)),
         contentDigest: await calculateEntryDigest(pluginRoot, true),
     };
 }
+async function validateBundleRuntimeRequirementsReceipts(plugin, pluginRoot) {
+    const files = await listBundleFiles(pluginRoot);
+    const expectedReceiptPaths = new Set(files.flatMap((relative) => /^(?:claude|codex|agent-skills)\/skills\/[^/]+\/SKILL\.md$/u.test(relative)
+        ? [path.posix.join(path.posix.dirname(relative), AW_PLUGIN_REQUIREMENTS_RECEIPT_FILENAME)]
+        : []));
+    const actualReceiptPaths = files.filter((relative) => path.posix.basename(relative) === AW_PLUGIN_REQUIREMENTS_RECEIPT_FILENAME);
+    for (const relative of expectedReceiptPaths) {
+        if (!actualReceiptPaths.includes(relative)) {
+            throw new Error(`Catalog plugin ${JSON.stringify(plugin.manifest.name)} Skill root is missing ${AW_PLUGIN_REQUIREMENTS_RECEIPT_FILENAME}: ${relative}.`);
+        }
+    }
+    const expected = createAwPluginRequirementsReceipt({ name: plugin.manifest.name, version: plugin.manifest.version }, plugin.manifest.requires?.aw.capabilities ?? []);
+    for (const relative of actualReceiptPaths) {
+        if (!expectedReceiptPaths.has(relative)) {
+            throw new Error(`Catalog plugin ${JSON.stringify(plugin.manifest.name)} has a reserved runtime requirements receipt outside a Skill root: ${relative}.`);
+        }
+        const receipt = parseAwPluginRequirementsReceipt(await readRegularJson(path.join(pluginRoot, ...relative.split('/')), `Catalog plugin ${JSON.stringify(plugin.manifest.name)} runtime requirements receipt`));
+        if (!isDeepStrictEqual(receipt, expected)) {
+            throw new Error(`Catalog plugin ${JSON.stringify(plugin.manifest.name)} has a mismatched runtime requirements receipt: ${relative}.`);
+        }
+    }
+}
 function normalizeCatalogRelease(raw, catalogVersion) {
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
         throw new Error('Invalid catalog manifest release: expected an object.');
@@ -521,7 +609,7 @@ export async function buildCatalogWorkspace(options) {
     const catalogVersion = catalogWorkspace.metadata.catalog.version;
     const channel = deriveCatalogChannel(catalogVersion);
     const pluginNames = plugins.map((plugin) => plugin.manifest.name).sort();
-    const identity = sourceIdentity(catalogWorkspace.metadata, plugins);
+    const identity = await calculateCatalogWorkspaceSourceIdentity(catalogWorkspace);
     const marker = generatedOutputMarker({
         kind: 'catalog',
         workspaceIdentity: catalogWorkspace.workspaceIdentity,
@@ -532,6 +620,7 @@ export async function buildCatalogWorkspace(options) {
         force: options.force === true,
         build: async (stagingRoot) => {
             const bundledPlugins = [];
+            await fs.ensureDir(path.join(stagingRoot, 'plugins'));
             for (const plugin of plugins) {
                 const closure = dependencyClosure(plugin, plugins);
                 const outputRoot = path.join(stagingRoot, 'plugins', plugin.manifest.name);
@@ -550,20 +639,14 @@ export async function buildCatalogWorkspace(options) {
                 .sort((left, right) => left.manifest.name.localeCompare(right.manifest.name));
             await fs.outputJson(path.join(stagingRoot, '.agents', 'plugins', 'marketplace.json'), createMarketplaceManifest(catalogWorkspace.metadata, byPlatform('codex')), { spaces: 2 });
             await fs.outputJson(path.join(stagingRoot, '.claude-plugin', 'marketplace.json'), createMarketplaceManifest(catalogWorkspace.metadata, byPlatform('claude')), { spaces: 2 });
-            let minVersion = '0.0.0';
-            for (const plugin of bundledPlugins) {
-                const candidate = plugin.manifest.compatibility.aw.minVersion;
-                if (compareStrictSemVer(candidate, minVersion) > 0)
-                    minVersion = candidate;
-            }
             const entries = await Promise.all([...bundledPlugins]
                 .sort((left, right) => left.manifest.name.localeCompare(right.manifest.name))
                 .map((plugin) => expectedCatalogEntry(plugin, plugin.rootDir)));
             const manifest = {
-                schemaVersion: 4,
+                schemaVersion: 5,
                 catalogVersion,
                 channel,
-                compatibility: { aw: { minVersion } },
+                requires: { aw: { capabilities: ['aw.catalog-snapshot.v5'] } },
                 marketplace: {
                     owner: catalogWorkspace.metadata.owner,
                     interface: catalogWorkspace.metadata.interface,
@@ -574,9 +657,9 @@ export async function buildCatalogWorkspace(options) {
             await fs.writeJson(path.join(stagingRoot, CATALOG_MANIFEST_FILENAME), manifest, { spaces: 2 });
             await fs.writeJson(path.join(stagingRoot, GENERATED_OUTPUT_MARKER_FILENAME), marker, { spaces: 2 });
         },
-        validate: async (stagingRoot) => { await validateCatalogSnapshot(stagingRoot); },
+        validate: async (stagingRoot) => { await validateCatalogSnapshotComplete(stagingRoot); },
         assertReplaceable: async (existingRoot) => {
-            await validateCatalogSnapshot(existingRoot);
+            await validateCatalogSnapshotComplete(existingRoot);
             await assertGeneratedOutput(existingRoot, marker);
         },
     });
@@ -596,10 +679,21 @@ async function rewritePublishedPluginVersions(snapshotRoot, overrides) {
             const manifest = await fs.readJson(manifestPath);
             await fs.writeFile(manifestPath, `${JSON.stringify({ ...manifest, version }, null, 2)}\n`);
         }
+        const pluginRoot = path.join(snapshotRoot, 'plugins', pluginName);
+        for (const relative of await listBundleFiles(pluginRoot)) {
+            if (path.posix.basename(relative) !== AW_PLUGIN_REQUIREMENTS_RECEIPT_FILENAME)
+                continue;
+            const receiptPath = path.join(pluginRoot, ...relative.split('/'));
+            const receipt = parseAwPluginRequirementsReceipt(await fs.readJson(receiptPath));
+            if (receipt.plugin.name !== pluginName) {
+                throw new Error(`Catalog plugin ${JSON.stringify(pluginName)} has a mismatched runtime requirements receipt.`);
+            }
+            await fs.writeFile(receiptPath, `${JSON.stringify(createAwPluginRequirementsReceipt({ name: pluginName, version }, receipt.requiredCapabilities), null, 2)}\n`);
+        }
     }
 }
 export async function validatePublishedCatalogSnapshot(snapshotDirectory) {
-    const validation = await validateCatalogSnapshot(snapshotDirectory);
+    const validation = await validateCatalogSnapshotComplete(snapshotDirectory);
     if (validation.manifest.release.state !== 'published') {
         throw new Error('Published Catalog snapshot must have release.state published.');
     }
@@ -618,10 +712,10 @@ export async function preparePublishedCatalogWorkspace(options) {
     const catalogVersion = catalogWorkspace.metadata.catalog.version;
     const channel = deriveCatalogChannel(catalogVersion);
     const previous = options.previousSnapshotRoot
-        ? await validatePublishedCatalogSnapshot(options.previousSnapshotRoot)
+        ? await validatePublishedCatalogPublicationParent(options.previousSnapshotRoot)
         : null;
-    if (previous && compareStrictSemVer(catalogVersion, previous.manifest.catalogVersion) <= 0) {
-        throw new Error(`Catalog version ${catalogVersion} must be higher than published ${previous.manifest.catalogVersion}.`);
+    if (previous && compareStrictSemVer(catalogVersion, previous.catalogVersion) <= 0) {
+        throw new Error(`Catalog version ${catalogVersion} must be higher than published ${previous.catalogVersion}.`);
     }
     const previousLedger = previous?.ledger ?? {
         schemaVersion: PLUGIN_RELEASE_LEDGER_SCHEMA_VERSION,
@@ -639,7 +733,7 @@ export async function preparePublishedCatalogWorkspace(options) {
             reservedImports: options.reservedImports,
         });
         temporaryRoot = built.outputRoot;
-        const development = await validateCatalogSnapshot(temporaryRoot);
+        const development = await validateCatalogSnapshotComplete(temporaryRoot);
         const contentDigests = new Map(development.manifest.entries.map((entry) => [entry.name, entry.contentDigest]));
         const overrides = channel === 'beta'
             ? resolveBetaPluginVersionOverrides({
@@ -828,7 +922,7 @@ async function digestDirectory(root) {
     await walk(root);
     return `sha256:${crypto.createHash('sha256').update(entries.join('\n')).digest('hex')}`;
 }
-export async function validateCatalogSnapshot(snapshotDirectory) {
+async function validateCatalogSnapshotTransportInternal(snapshotDirectory, options = {}) {
     const rootDir = await assertDirectoryWithoutSymlinks(snapshotDirectory, 'Catalog snapshot');
     const allowed = new Set([
         CATALOG_MANIFEST_FILENAME,
@@ -876,16 +970,20 @@ export async function validateCatalogSnapshot(snapshotDirectory) {
     await readRegularJson(path.join(rootDir, '.agents', 'plugins', 'marketplace.json'), 'Codex marketplace');
     await readRegularJson(path.join(rootDir, '.claude-plugin', 'marketplace.json'), 'Claude marketplace');
     const snapshotDigest = await digestDirectory(rootDir);
-    const raw = await fs.readJson(path.join(rootDir, CATALOG_MANIFEST_FILENAME));
+    const raw = options.rawManifest
+        ?? await fs.readJson(path.join(rootDir, CATALOG_MANIFEST_FILENAME));
     const allowedManifestKeys = new Set([
-        'schemaVersion', 'catalogVersion', 'channel', 'compatibility', 'marketplace', 'release', 'entries',
+        'schemaVersion', 'catalogVersion', 'channel', 'requires', 'marketplace', 'release', 'entries',
     ]);
     for (const key of Object.keys(raw))
         if (!allowedManifestKeys.has(key))
             throw new Error(`Invalid catalog manifest: unknown field ${JSON.stringify(key)}.`);
-    if (raw.schemaVersion !== 4)
-        throw new Error('Invalid catalog manifest schemaVersion: expected 4.');
-    const base = normalizeCatalogManifestBase(raw, 'catalog manifest v4');
+    if (raw.schemaVersion !== 5)
+        throw new Error('Invalid catalog manifest schemaVersion: expected 5.');
+    const base = normalizeCatalogManifestBase(raw, 'catalog manifest v5');
+    if (!(base.requires.aw.capabilities ?? []).includes('aw.catalog-snapshot.v5')) {
+        throw new Error('Invalid catalog manifest requires.aw.capabilities: expected aw.catalog-snapshot.v5.');
+    }
     const marketplaceIdentity = normalizeCatalogMarketplaceIdentity(raw.marketplace);
     if (!Array.isArray(raw.entries))
         throw new Error('Invalid catalog manifest entries: expected an array.');
@@ -901,7 +999,7 @@ export async function validateCatalogSnapshot(snapshotDirectory) {
         delete copy.contentDigest;
         return copy;
     });
-    const normalizedEntries = normalizeCatalogManifestEntries(entriesWithoutContentDigest, base, 'catalog manifest v4')
+    const normalizedEntries = normalizeCatalogManifestEntries(entriesWithoutContentDigest, base, 'catalog manifest v5')
         .map((entry, index) => ({ ...entry, contentDigest: contentDigests[index] }));
     const pluginNames = normalizedEntries.map((entry, index) => {
         if (typeof entry.name !== 'string')
@@ -915,39 +1013,61 @@ export async function validateCatalogSnapshot(snapshotDirectory) {
     const diskNames = (await fs.readdir(path.join(rootDir, 'plugins'))).sort();
     if (diskNames.join('\0') !== [...pluginNames].sort().join('\0'))
         throw new Error('Invalid catalog snapshot plugin inventory.');
-    const plugins = [];
+    const platformEntries = {
+        claude: [],
+        codex: [],
+    };
     for (const [index, name] of pluginNames.entries()) {
         const pluginRoot = path.join(rootDir, 'plugins', name);
-        const plugin = await readPluginManifest(pluginRoot, { mode: 'bundle' });
+        await assertDirectoryWithoutSymlinks(pluginRoot, `Catalog plugin ${JSON.stringify(name)}`);
+        const entry = normalizedEntries[index];
+        if (entry.source !== `./plugins/${name}`) {
+            throw new Error(`Catalog entry source for ${JSON.stringify(name)} does not match its plugin bundle.`);
+        }
+        const rawBundleManifest = await readRegularJson(path.join(pluginRoot, SOURCE_MANIFEST_PATH), `Catalog plugin ${JSON.stringify(name)} bundle manifest`);
+        const expectedDigests = {
+            artifactDigest: await calculateEntryDigest(pluginRoot, false),
+            manifestDigest: sha256(normalizeManifestDigestInput(rawBundleManifest)),
+            contentDigest: await calculateEntryDigest(pluginRoot, true),
+        };
+        for (const field of Object.keys(expectedDigests)) {
+            // V4 used a normalized Manifest v1 digest. The artifact digest still binds the raw manifest bytes,
+            // and the release ledger must still match the preserved v4 manifestDigest.
+            if (field === 'manifestDigest' && options.legacyV4PublicationParent)
+                continue;
+            if (entry[field] !== expectedDigests[field]) {
+                throw new Error(`Catalog entry ${field} for ${JSON.stringify(name)} does not match its plugin bundle.`);
+            }
+        }
         for (const platform of ['claude', 'codex']) {
             const platformManifest = path.join(pluginRoot, `.${platform}-plugin`, 'plugin.json');
             const exists = await fs.pathExists(platformManifest);
-            if (exists !== resolveSupportedPlatforms(plugin.manifest).has(platform)) {
-                throw new Error(`Catalog plugin ${JSON.stringify(name)} has an inconsistent ${platform} bundle projection.`);
-            }
             if (exists) {
-                const rawPlatformManifest = await readRegularJson(platformManifest, `${platform} plugin manifest`);
-                await validatePlatformManifestProjection(plugin, platform, rawPlatformManifest);
+                await readRegularJson(platformManifest, `${platform} plugin manifest`);
+                platformEntries[platform].push(entry);
             }
         }
-        const expected = await expectedCatalogEntry(plugin, pluginRoot);
-        for (const field of Object.keys(expected)) {
-            if (!isDeepStrictEqual(normalizedEntries[index][field], expected[field])) {
-                throw new Error(`Catalog entry ${field} for ${JSON.stringify(name)} does not match its plugin bundle.`);
-            }
-        }
-        plugins.push(plugin);
     }
-    assertDependencyGraph(plugins);
     const agentsMarketplace = await fs.readJson(path.join(rootDir, '.agents', 'plugins', 'marketplace.json'));
     const claudeMarketplace = await fs.readJson(path.join(rootDir, '.claude-plugin', 'marketplace.json'));
-    const marketplaceMetadata = {
+    const marketplaceEntry = (entry) => ({
+        name: entry.name,
+        source: entry.source,
+        description: entry.description,
+        interface: entry.interface,
+        category: entry.category,
+        tags: entry.tags,
+        strict: entry.strict,
+        policy: entry.policy,
+    });
+    const expectedMarketplace = (platform) => ({
+        name: 'aw',
         owner: marketplaceIdentity.owner,
         interface: marketplaceIdentity.interface,
-        catalog: { version: base.catalogVersion },
-    };
-    const expectedAgents = createMarketplaceManifest(marketplaceMetadata, plugins.filter((plugin) => resolveSupportedPlatforms(plugin.manifest).has('codex')));
-    const expectedClaude = createMarketplaceManifest(marketplaceMetadata, plugins.filter((plugin) => resolveSupportedPlatforms(plugin.manifest).has('claude')));
+        plugins: platformEntries[platform].map(marketplaceEntry),
+    });
+    const expectedAgents = expectedMarketplace('codex');
+    const expectedClaude = expectedMarketplace('claude');
     const normalizeMarketplaceOrder = (marketplace) => {
         const canonical = JSON.parse(JSON.stringify(marketplace));
         return {
@@ -965,10 +1085,10 @@ export async function validateCatalogSnapshot(snapshotDirectory) {
     }
     const release = normalizeCatalogRelease(raw.release, base.catalogVersion);
     const manifest = {
-        schemaVersion: 4,
+        schemaVersion: 5,
         catalogVersion: base.catalogVersion,
         channel: base.channel,
-        compatibility: base.compatibility,
+        requires: base.requires,
         marketplace: marketplaceIdentity,
         release,
         entries: normalizedEntries,
@@ -991,4 +1111,178 @@ export async function validateCatalogSnapshot(snapshotDirectory) {
         : undefined;
     return { rootDir, manifest, ...(ledger ? { ledger } : {}), snapshotDigest };
 }
+export async function validateCatalogSnapshotTransport(snapshotDirectory) {
+    return validateCatalogSnapshotTransportInternal(snapshotDirectory);
+}
+function normalizeLegacyCatalogCompatibility(value, fieldName) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`Invalid ${fieldName}: expected an object.`);
+    }
+    const compatibility = value;
+    if (!isDeepStrictEqual(Object.keys(compatibility), ['aw'])) {
+        throw new Error(`Invalid ${fieldName}: unknown field.`);
+    }
+    if (!compatibility.aw || typeof compatibility.aw !== 'object' || Array.isArray(compatibility.aw)) {
+        throw new Error(`Invalid ${fieldName}.aw: expected an object.`);
+    }
+    const aw = compatibility.aw;
+    if (!isDeepStrictEqual(Object.keys(aw), ['minVersion'])) {
+        throw new Error(`Invalid ${fieldName}.aw: unknown field.`);
+    }
+    return { aw: { minVersion: assertStrictSemVer(aw.minVersion, `${fieldName}.aw.minVersion`) } };
+}
+function normalizeLegacyPublishedCatalogManifestV4(raw) {
+    const allowedManifestKeys = new Set([
+        'schemaVersion', 'catalogVersion', 'channel', 'compatibility', 'marketplace', 'release', 'entries',
+    ]);
+    for (const key of Object.keys(raw)) {
+        if (!allowedManifestKeys.has(key))
+            throw new Error(`Invalid legacy catalog manifest: unknown field ${JSON.stringify(key)}.`);
+    }
+    if (raw.schemaVersion !== 4)
+        throw new Error('Invalid legacy catalog manifest schemaVersion: expected 4.');
+    const catalogVersion = assertCatalogVersion(raw.catalogVersion, 'legacy catalog manifest v4.catalogVersion');
+    if (raw.channel !== 'latest' && raw.channel !== 'beta') {
+        throw new Error('Invalid legacy catalog manifest v4.channel: expected "latest" or "beta".');
+    }
+    const channel = raw.channel;
+    const isBetaVersion = catalogVersion.includes('-beta.');
+    if ((channel === 'latest' && isBetaVersion) || (channel === 'beta' && !isBetaVersion)) {
+        throw new Error('Invalid legacy catalog manifest v4 catalogVersion channel.');
+    }
+    const compatibility = normalizeLegacyCatalogCompatibility(raw.compatibility, 'legacy catalog manifest v4.compatibility');
+    const marketplace = normalizeCatalogMarketplaceIdentity(raw.marketplace, 'legacy catalog manifest v4.marketplace');
+    if (!Array.isArray(raw.entries))
+        throw new Error('Invalid legacy catalog manifest v4.entries: expected an array.');
+    const allowedEntryKeys = new Set([
+        'name', 'version', 'description', 'interface', 'category', 'tags', 'strict', 'policy',
+        'compatibility', 'source', 'artifactDigest', 'manifestDigest', 'contentDigest',
+    ]);
+    const translatedEntryInputs = raw.entries.map((value, index) => {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            throw new Error(`Invalid legacy catalog manifest v4.entries[${index}]: expected an object.`);
+        }
+        const entry = value;
+        for (const key of Object.keys(entry)) {
+            if (!allowedEntryKeys.has(key)) {
+                throw new Error(`Invalid legacy catalog manifest v4.entries[${index}]: unknown field ${JSON.stringify(key)}.`);
+            }
+        }
+        const entryCompatibility = normalizeLegacyCatalogCompatibility(entry.compatibility, `legacy catalog manifest v4.entries[${index}].compatibility`);
+        if (compareStrictSemVer(entryCompatibility.aw.minVersion, compatibility.aw.minVersion) < 0) {
+            throw new Error(`Invalid legacy catalog manifest v4.entries[${index}].compatibility.aw.minVersion.`);
+        }
+        const translated = { ...entry };
+        delete translated.compatibility;
+        delete translated.contentDigest;
+        return {
+            ...translated,
+            dependencies: [],
+            requires: { aw: { capabilities: [] } },
+        };
+    });
+    const translatedBase = normalizeCatalogManifestBase({
+        catalogVersion,
+        channel,
+        requires: { aw: { capabilities: ['aw.catalog-snapshot.v5'] } },
+    }, 'legacy catalog manifest v4 translation');
+    const normalizedEntries = normalizeCatalogManifestEntries(translatedEntryInputs, translatedBase, 'legacy catalog manifest v4 translation').map((entry, index) => {
+        const contentDigest = raw.entries[index].contentDigest;
+        if (typeof contentDigest !== 'string' || !/^sha256:[0-9a-f]{64}$/u.test(contentDigest)) {
+            throw new Error(`Invalid legacy catalog manifest v4.entries[${index}].contentDigest.`);
+        }
+        return { ...entry, contentDigest };
+    });
+    const release = normalizeCatalogRelease(raw.release, catalogVersion);
+    if (release.state !== 'published') {
+        throw new Error('Legacy Catalog publication parent must have release.state published.');
+    }
+    const legacyContentDigest = sha256(stableStringify({
+        schemaIdentity: { schemaVersion: 4 },
+        marketplaceMetadata: { name: 'aw', owner: marketplace.owner, interface: marketplace.interface },
+        compatibility,
+        plugins: normalizedEntries.map((entry) => ({
+            name: entry.name,
+            targetVersion: entry.version.replace(/-beta\.[1-9]\d*$/u, ''),
+            contentDigest: entry.contentDigest,
+        })).sort((left, right) => left.name.localeCompare(right.name)),
+    }));
+    if (release.contentDigest !== legacyContentDigest) {
+        throw new Error('Published legacy catalog release contentDigest does not match the snapshot.');
+    }
+    const translatedManifest = {
+        schemaVersion: 5,
+        catalogVersion,
+        channel,
+        requires: translatedBase.requires,
+        marketplace,
+        release,
+        entries: normalizedEntries,
+    };
+    return {
+        ...translatedManifest,
+        release: { ...release, contentDigest: publishedContentDigest(translatedManifest) },
+    };
+}
+export async function validatePublishedCatalogPublicationParent(snapshotDirectory) {
+    const raw = await readRegularJson(path.join(snapshotDirectory, CATALOG_MANIFEST_FILENAME), 'Catalog publication parent manifest');
+    const validation = raw.schemaVersion === 4
+        ? await validateCatalogSnapshotTransportInternal(snapshotDirectory, {
+            rawManifest: normalizeLegacyPublishedCatalogManifestV4(raw),
+            legacyV4PublicationParent: true,
+        })
+        : await validatePublishedCatalogSnapshot(snapshotDirectory);
+    if (validation.manifest.release.state !== 'published') {
+        throw new Error('Catalog publication parent must have release.state published.');
+    }
+    if (!validation.ledger)
+        throw new Error('Catalog publication parent must include a plugin release ledger.');
+    return {
+        rootDir: validation.rootDir,
+        catalogVersion: validation.manifest.catalogVersion,
+        ledger: validation.ledger,
+        snapshotDigest: validation.snapshotDigest,
+    };
+}
+async function validateCatalogPluginEntriesComplete(validation, pluginNames) {
+    const entriesByName = new Map(validation.manifest.entries.map((entry) => [entry.name, entry]));
+    const plugins = [];
+    for (const name of pluginNames) {
+        const entry = entriesByName.get(name);
+        if (!entry)
+            throw new Error(`Catalog plugin ${JSON.stringify(name)} does not exist.`);
+        const pluginRoot = path.join(validation.rootDir, 'plugins', entry.name);
+        const plugin = await readPluginManifest(pluginRoot, { mode: 'bundle' });
+        await validateBundleRuntimeRequirementsReceipts(plugin, pluginRoot);
+        for (const platform of ['claude', 'codex']) {
+            const platformManifestPath = path.join(pluginRoot, `.${platform}-plugin`, 'plugin.json');
+            const exists = await fs.pathExists(platformManifestPath);
+            if (exists !== resolveSupportedPlatforms(plugin.manifest).has(platform)) {
+                throw new Error(`Catalog plugin ${JSON.stringify(entry.name)} has an inconsistent ${platform} bundle projection.`);
+            }
+            if (exists) {
+                const rawPlatformManifest = await readRegularJson(platformManifestPath, `${platform} plugin manifest`);
+                await validatePlatformManifestProjection(plugin, platform, rawPlatformManifest);
+            }
+        }
+        const expected = await expectedCatalogEntry(plugin, pluginRoot);
+        for (const field of Object.keys(expected)) {
+            if (!isDeepStrictEqual(entry[field], expected[field])) {
+                throw new Error(`Catalog entry ${field} for ${JSON.stringify(entry.name)} does not match its plugin bundle.`);
+            }
+        }
+        plugins.push(plugin);
+    }
+    assertDependencyGraph(plugins);
+}
+export async function validateCatalogSnapshotPluginEntriesComplete(snapshotDirectory, pluginNames) {
+    const validation = await validateCatalogSnapshotTransport(snapshotDirectory);
+    await validateCatalogPluginEntriesComplete(validation, pluginNames);
+    return validation;
+}
+export async function validateCatalogSnapshotComplete(snapshotDirectory) {
+    const validation = await validateCatalogSnapshotTransport(snapshotDirectory);
+    await validateCatalogPluginEntriesComplete(validation, validation.manifest.entries.map((entry) => entry.name));
+    return validation;
+}
 //# sourceMappingURL=workspace.js.map