@lesliechan721/aw-plugin-core 0.1.0-beta.6 → 0.1.0-beta.61

package/dist/workspace.js

@@ -2,9 +2,10 @@ import crypto from 'node:crypto';
 import path from 'node:path';
 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 { catalogFileMode, listCatalogBundleFiles as listBundleFiles, readCatalogExecutableFiles, writeCatalogExecutableFiles, } from './catalog-file-modes.js';
+import { assertCatalogVersion, assertStrictSemVer, compareStrictSemVer, parseStrictSemVer, 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 { appendCatalogToPluginReleaseLedger, assertStablePluginVersion, PLUGIN_RELEASE_LEDGER_FILENAME, PLUGIN_RELEASE_LEDGER_SCHEMA_VERSION, resolveBetaPluginVersionOverrides, validatePluginReleaseLedgerAgainstManifest, } from './plugin-release.js';
+import { createAwPluginRequirementsReceipt, normalizeAwCapabilities, parseAwPluginRequirementsReceipt, } from './aw-capabilities.js';
 export const DEFAULT_CATALOG_WORKSPACE_VERSION = '0.1.0';
 export const DEFAULT_CATALOG_OUTPUT_PATH = path.join('.aw', 'catalog');
 export const DEFAULT_PUBLISHED_CATALOG_OUTPUT_PATH = path.join('.aw', 'publish', '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 !== '..'
@@ -138,9 +140,18 @@ function validateCatalogWorkspaceMarker(value) {
     }
     return { workspaceIdentity: marker.workspaceIdentity };
 }
-async function readCatalogWorkspaceMarker(workspaceRoot) {
+export async function readCatalogWorkspaceMarker(workspaceRoot) {
     const markerPath = path.join(workspaceRoot, CATALOG_WORKSPACE_MARKER_FILENAME);
-    const marker = validateCatalogWorkspaceMarker(await readRegularJson(markerPath, 'Catalog Workspace marker'));
+    let value;
+    try {
+        value = await readRegularJson(markerPath, 'Catalog Workspace marker');
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            throw new Error('Invalid Catalog Workspace marker.');
+        throw error;
+    }
+    const marker = validateCatalogWorkspaceMarker(value);
     return { markerPath, workspaceIdentity: marker.workspaceIdentity };
 }
 async function readRegularJson(filePath, label) {
@@ -398,29 +409,54 @@ function stableStringify(value) {
 function sha256(value) {
     return `sha256:${crypto.createHash('sha256').update(value).digest('hex')}`;
 }
-function publishedContentDigest(manifest) {
-    return sha256(stableStringify({
-        schemaIdentity: { schemaVersion: manifest.schemaVersion },
-        marketplaceMetadata: {
-            name: 'aw',
-            owner: manifest.marketplace.owner,
-            interface: manifest.marketplace.interface,
-        },
-        compatibility: manifest.compatibility,
-        plugins: manifest.entries.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)),
-    }));
-}
-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 {
@@ -431,46 +467,93 @@ function generatedOutputMarker(options) {
         ...(options.sourceName ? { sourceName: options.sourceName } : {}),
     };
 }
-async function listBundleFiles(root, relative = '') {
-    const result = [];
-    for (const entry of await fs.readdir(path.join(root, relative), { withFileTypes: true })) {
-        const child = relative ? path.posix.join(relative, entry.name) : entry.name;
-        if (entry.isDirectory())
-            result.push(...await listBundleFiles(root, child));
-        else
-            result.push(child);
-    }
-    return result.sort();
-}
-async function catalogPathRecord(root, relative, versionNeutral) {
+async function catalogPathRecords(root, relative, executableFiles) {
     const filePath = path.join(root, ...relative.split('/'));
     const stat = await fs.lstat(filePath);
     if (stat.isSymbolicLink()) {
-        return { path: relative, kind: 'symlink', mode: '120000', digest: sha256(await fs.readlink(filePath)) };
+        const record = { path: relative, kind: 'symlink', mode: '120000', digest: sha256(await fs.readlink(filePath)) };
+        return { artifact: record, content: record };
     }
     if (!stat.isFile())
         throw new Error(`Catalog digest path must be a regular file or symlink: ${filePath}.`);
+    const bytes = await fs.readFile(filePath);
+    const artifact = {
+        path: relative,
+        kind: 'file',
+        mode: catalogFileMode(relative, stat.mode, executableFiles),
+        digest: sha256(bytes),
+    };
     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));
-    return { path: relative, kind: 'file', mode: (stat.mode & 0o100) === 0 ? '100644' : '100755', digest };
+    let contentDigest = artifact.digest;
+    if (manifests.has(relative)) {
+        // Match readJson's UTF-8 BOM handling while reusing the original bytes.
+        const manifest = JSON.parse(bytes.toString('utf8').replace(/^\uFEFF/u, ''));
+        contentDigest = sha256(stableStringify({
+            ...manifest,
+            version: '<plugin-version>',
+        }));
+    }
+    else if (path.posix.basename(relative) === AW_PLUGIN_REQUIREMENTS_RECEIPT_FILENAME) {
+        const receipt = JSON.parse(bytes.toString('utf8').replace(/^\uFEFF/u, ''));
+        const plugin = receipt.plugin && typeof receipt.plugin === 'object' && !Array.isArray(receipt.plugin)
+            ? receipt.plugin
+            : {};
+        contentDigest = sha256(stableStringify({
+            ...receipt,
+            plugin: { ...plugin, version: '<plugin-version>' },
+        }));
+    }
+    return { artifact, content: contentDigest === artifact.digest ? artifact : { ...artifact, digest: contentDigest } };
 }
-async function calculateEntryDigest(root, versionNeutral) {
+async function calculateEntryDigests(root) {
     const files = await listBundleFiles(root);
-    return sha256(stableStringify(await Promise.all(files.map((file) => catalogPathRecord(root, file, versionNeutral)))));
+    const executableFiles = await readCatalogExecutableFiles(root, files);
+    const records = await Promise.all(files.map((file) => catalogPathRecords(root, file, executableFiles)));
+    return {
+        artifactDigest: sha256(stableStringify(records.map((record) => record.artifact))),
+        contentDigest: sha256(stableStringify(records.map((record) => record.content))),
+    };
 }
 async function expectedCatalogEntry(plugin, pluginRoot) {
+    const bundleManifest = await readRegularJson(path.join(pluginRoot, SOURCE_MANIFEST_PATH), `Catalog plugin ${JSON.stringify(plugin.manifest.name)} bundle manifest`);
+    const digests = await calculateEntryDigests(pluginRoot);
     return {
         ...createMarketplaceManifestEntry(plugin),
         version: plugin.manifest.version,
-        compatibility: plugin.manifest.compatibility,
-        artifactDigest: await calculateEntryDigest(pluginRoot, false),
-        manifestDigest: sha256(normalizeManifestDigestInput(plugin.manifest)),
-        contentDigest: await calculateEntryDigest(pluginRoot, true),
+        dependencies: [...(plugin.manifest.dependencies ?? [])].sort(),
+        requires: {
+            aw: {
+                capabilities: normalizeAwCapabilities(plugin.manifest.requires?.aw.capabilities ?? []),
+            },
+        },
+        artifactDigest: digests.artifactDigest,
+        manifestDigest: sha256(normalizeManifestDigestInput(bundleManifest)),
+        contentDigest: digests.contentDigest,
     };
 }
-function normalizeCatalogRelease(raw, catalogVersion) {
+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) {
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
         throw new Error('Invalid catalog manifest release: expected an object.');
     }
@@ -481,33 +564,16 @@ function normalizeCatalogRelease(raw, catalogVersion) {
         }
         return { state: 'development' };
     }
-    const allowed = new Set(['state', 'targetVersion', 'planId', 'sourceHead', 'contentDigest']);
+    const allowed = new Set(['state', 'sourceHead']);
     if (release.state !== 'published' || Object.keys(release).some((key) => !allowed.has(key))) {
         throw new Error('Invalid published catalog release.');
     }
-    const targetVersion = assertStrictSemVer(release.targetVersion, 'catalog release targetVersion');
-    if (targetVersion.includes('-') || targetVersion.includes('+')) {
-        throw new Error('Invalid catalog release targetVersion: expected a stable version.');
-    }
-    if (targetVersion !== catalogVersion.replace(/-beta\.[1-9]\d*$/u, '')) {
-        throw new Error('Invalid catalog release targetVersion: must match catalogVersion.');
-    }
-    const digestPattern = /^sha256:[0-9a-f]{64}$/u;
-    if (typeof release.planId !== 'string' || !digestPattern.test(release.planId)) {
-        throw new Error('Invalid catalog release planId.');
-    }
-    if (typeof release.contentDigest !== 'string' || !digestPattern.test(release.contentDigest)) {
-        throw new Error('Invalid catalog release contentDigest.');
-    }
     if (typeof release.sourceHead !== 'string' || !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/u.test(release.sourceHead)) {
         throw new Error('Invalid catalog release sourceHead.');
     }
     return {
         state: 'published',
-        targetVersion,
-        planId: release.planId,
         sourceHead: release.sourceHead,
-        contentDigest: release.contentDigest,
     };
 }
 export async function buildCatalogWorkspace(options) {
@@ -521,7 +587,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 +598,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);
@@ -543,6 +610,7 @@ export async function buildCatalogWorkspace(options) {
                     dependencies: closure.slice(0, -1),
                     outputRoot,
                 });
+                await writeCatalogExecutableFiles(outputRoot);
                 bundledPlugins.push(await readPluginManifest(outputRoot, { mode: 'bundle' }));
             }
             const byPlatform = (platform) => bundledPlugins
@@ -550,20 +618,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: 7,
                 catalogVersion,
                 channel,
-                compatibility: { aw: { minVersion } },
+                requires: { aw: { capabilities: ['aw.catalog-snapshot.v7'] } },
                 marketplace: {
                     owner: catalogWorkspace.metadata.owner,
                     interface: catalogWorkspace.metadata.interface,
@@ -574,9 +636,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,16 +658,132 @@ 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`);
+        }
+    }
+}
+function assertStablePluginVersion(version, fieldName) {
+    const parsed = parseStrictSemVer(version, fieldName);
+    if (parsed.prerelease.length > 0 || parsed.build.length > 0) {
+        throw new Error(`Invalid ${fieldName}: expected a stable SemVer without prerelease or build metadata.`);
+    }
+    return version;
+}
+function stableVersionBase(version, fieldName) {
+    const parsed = parseStrictSemVer(version, fieldName);
+    return `${parsed.major}.${parsed.minor}.${parsed.patch}`;
+}
+/**
+ * Assign versions for planning and snapshot preparation with the same content comparison.
+ * Official history includes removed Plugins. Baseline declarations come from main source,
+ * before generated candidate metadata changes.
+ */
+export function resolvePublishedPluginVersions(options) {
+    const official = options.officialPluginHistory !== undefined;
+    const previousEntries = new Map();
+    const historicalContents = new Map();
+    for (const entry of [...options.previousPluginEntries ?? [], ...options.officialPluginHistory ?? []]) {
+        if (official) {
+            assertCatalogVersion(entry.version, `${entry.name} previous published version`);
+            const key = `${entry.name}@${entry.version}`;
+            const content = historicalContents.get(key);
+            if (content !== undefined && content !== entry.contentDigest) {
+                throw new Error(`Plugin ${entry.name} version ${entry.version} maps to different content in published history.`);
+            }
+            historicalContents.set(key, entry.contentDigest);
+            const previous = previousEntries.get(entry.name);
+            if (previous && compareStrictSemVer(previous.version, entry.version) >= 0)
+                continue;
+        }
+        previousEntries.set(entry.name, entry);
+    }
+    const versions = {};
+    for (const entry of options.entries) {
+        const { name, contentDigest } = entry;
+        if (!contentDigest)
+            throw new Error(`Missing release content digest for plugin ${JSON.stringify(name)}.`);
+        const sourceVersion = assertStablePluginVersion(entry.version, `${name} source version`);
+        const previous = previousEntries.get(name);
+        if (!previous) {
+            versions[name] = options.channel === 'beta' ? `${sourceVersion}-beta.1` : sourceVersion;
+            continue;
+        }
+        const previousVersion = assertStrictSemVer(previous.version, `${name} previous published version`);
+        const previousBase = stableVersionBase(previousVersion, `${name} previous published version`);
+        const baseComparison = compareStrictSemVer(sourceVersion, previousBase);
+        const parsedPrevious = parseStrictSemVer(previousVersion, `${name} previous published version`);
+        const baselineSourceVersion = options.sourcePluginVersionsAtBaseline?.[name];
+        if (official && baselineSourceVersion !== undefined
+            && sourceVersion !== assertStablePluginVersion(baselineSourceVersion, `${name} baseline source version`)) {
+            if (baseComparison < 0) {
+                throw new Error(`Plugin ${name} explicit source version ${sourceVersion} must not be lower than published base ${previousBase}.`);
+            }
+            if (baseComparison === 0 && parsedPrevious.prerelease.length === 0) {
+                throw new Error(`Plugin ${name} explicit source version ${sourceVersion} is already published as stable. Select a higher base.`);
+            }
+        }
+        if (options.channel === 'latest') {
+            const comparison = compareStrictSemVer(sourceVersion, previousVersion);
+            if (!official && comparison < 0) {
+                throw new Error(`Plugin ${name} source version ${sourceVersion} must not be lower than previous ${previousVersion}.`);
+            }
+            if (!official && comparison === 0 && previous.contentDigest !== contentDigest) {
+                throw new Error(`Plugin ${name} version ${sourceVersion} maps to different content. Increase the source plugin version.`);
+            }
+            let version = sourceVersion;
+            if (official && baseComparison <= 0) {
+                version = previousBase;
+                if (parsedPrevious.prerelease.length === 0 && previous.contentDigest !== contentDigest) {
+                    version = `${parsedPrevious.major}.${parsedPrevious.minor}.${parsedPrevious.patch + 1}`;
+                }
+            }
+            versions[name] = version;
+            continue;
+        }
+        if (!official && baseComparison < 0) {
+            throw new Error(`Plugin ${name} source version ${sourceVersion} must not be lower than previous base ${previousBase}.`);
+        }
+        if (baseComparison > 0) {
+            versions[name] = `${sourceVersion}-beta.1`;
+            continue;
+        }
+        if (parsedPrevious.prerelease.length === 0) {
+            if (previous.contentDigest !== contentDigest) {
+                if (!official) {
+                    throw new Error(`Plugin ${name} stable version ${sourceVersion} maps to different content. Increase the source plugin version.`);
+                }
+                versions[name] = `${parsedPrevious.major}.${parsedPrevious.minor}.${parsedPrevious.patch + 1}-beta.1`;
+                continue;
+            }
+            versions[name] = previousVersion;
+            continue;
+        }
+        if (parsedPrevious.prerelease.length !== 2
+            || parsedPrevious.prerelease[0] !== 'beta'
+            || !/^[1-9]\d*$/u.test(parsedPrevious.prerelease[1])) {
+            throw new Error(`Plugin ${name} previous version ${previousVersion} is not a stable or beta publication version.`);
+        }
+        versions[name] = previous.contentDigest === contentDigest
+            ? previousVersion
+            : `${previousBase}-beta.${Number(parsedPrevious.prerelease[1]) + 1}`;
     }
+    return versions;
 }
 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.');
     }
-    if (!validation.ledger)
-        throw new Error('Published Catalog snapshot must include a plugin release ledger.');
-    return { ...validation, ledger: validation.ledger };
+    return validation;
 }
 export async function preparePublishedCatalogWorkspace(options) {
     if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/u.test(options.sourceHead)) {
@@ -620,13 +798,12 @@ export async function preparePublishedCatalogWorkspace(options) {
     const previous = options.previousSnapshotRoot
         ? await validatePublishedCatalogSnapshot(options.previousSnapshotRoot)
         : null;
+    if (!previous && (options.historicalPluginEntries?.length ?? 0) > 0) {
+        throw new Error('Published Plugin history requires a previous Catalog snapshot.');
+    }
     if (previous && compareStrictSemVer(catalogVersion, previous.manifest.catalogVersion) <= 0) {
         throw new Error(`Catalog version ${catalogVersion} must be higher than published ${previous.manifest.catalogVersion}.`);
     }
-    const previousLedger = previous?.ledger ?? {
-        schemaVersion: PLUGIN_RELEASE_LEDGER_SCHEMA_VERSION,
-        records: [],
-    };
     const temporaryRelative = path.join('.aw', 'publish', `.catalog-preparation-${crypto.randomUUID()}`);
     const finalRelative = options.outputPath
         ?? `${DEFAULT_PUBLISHED_CATALOG_OUTPUT_PATH}-v${catalogVersion}`;
@@ -639,15 +816,14 @@ export async function preparePublishedCatalogWorkspace(options) {
             reservedImports: options.reservedImports,
         });
         temporaryRoot = built.outputRoot;
-        const development = await validateCatalogSnapshot(temporaryRoot);
-        const contentDigests = new Map(development.manifest.entries.map((entry) => [entry.name, entry.contentDigest]));
-        const overrides = channel === 'beta'
-            ? resolveBetaPluginVersionOverrides({
-                plugins: catalogWorkspace.plugins,
-                contentDigests,
-                ledger: previousLedger,
-            })
-            : Object.fromEntries(catalogWorkspace.plugins.map((plugin) => [plugin.manifest.name, plugin.manifest.version]));
+        const development = await validateCatalogSnapshotComplete(temporaryRoot);
+        const overrides = resolvePublishedPluginVersions({
+            channel,
+            entries: development.manifest.entries,
+            previousPluginEntries: [...options.historicalPluginEntries ?? [], ...previous?.manifest.entries ?? []],
+            officialPluginHistory: options.officialPluginHistory,
+            sourcePluginVersionsAtBaseline: options.sourcePluginVersionsAtBaseline,
+        });
         await rewritePublishedPluginVersions(temporaryRoot, overrides);
         const bundledPlugins = await Promise.all(catalogWorkspace.plugins.map((plugin) => readPluginManifest(path.join(temporaryRoot, 'plugins', plugin.manifest.name), { mode: 'bundle' })));
         const entries = await Promise.all(bundledPlugins.sort((left, right) => left.manifest.name.localeCompare(right.manifest.name))
@@ -658,26 +834,14 @@ export async function preparePublishedCatalogWorkspace(options) {
             channel,
             entries,
         };
-        const contentDigest = publishedContentDigest(manifestWithoutRelease);
         const manifest = {
             ...manifestWithoutRelease,
             release: {
                 state: 'published',
-                targetVersion: catalogVersion.replace(/-beta\.[1-9]\d*$/u, ''),
-                planId: contentDigest,
                 sourceHead: options.sourceHead,
-                contentDigest,
             },
         };
-        const ledger = appendCatalogToPluginReleaseLedger({
-            previous: previousLedger,
-            manifest,
-            contentDigests,
-        });
-        await Promise.all([
-            fs.writeFile(path.join(temporaryRoot, CATALOG_MANIFEST_FILENAME), `${JSON.stringify(manifest, null, 2)}\n`),
-            fs.writeFile(path.join(temporaryRoot, PLUGIN_RELEASE_LEDGER_FILENAME), `${JSON.stringify(ledger, null, 2)}\n`),
-        ]);
+        await fs.writeFile(path.join(temporaryRoot, CATALOG_MANIFEST_FILENAME), `${JSON.stringify(manifest, null, 2)}\n`);
         const prepared = await validatePublishedCatalogSnapshot(temporaryRoot);
         const resolved = await resolveCatalogWorkspaceOutputPath({
             workspaceRoot: catalogWorkspace.workspaceRoot,
@@ -701,8 +865,6 @@ export async function preparePublishedCatalogWorkspace(options) {
             channel,
             pluginNames: built.pluginNames,
             snapshotDigest: prepared.snapshotDigest,
-            contentDigest,
-            planId: contentDigest,
         };
     }
     finally {
@@ -828,7 +990,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) {
     const rootDir = await assertDirectoryWithoutSymlinks(snapshotDirectory, 'Catalog snapshot');
     const allowed = new Set([
         CATALOG_MANIFEST_FILENAME,
@@ -836,7 +998,6 @@ export async function validateCatalogSnapshot(snapshotDirectory) {
         '.agents',
         '.claude-plugin',
         'plugins',
-        'plugin-release-ledger.json',
     ]);
     const entries = await fs.readdir(rootDir);
     const unexpected = entries.filter((entry) => !allowed.has(entry));
@@ -846,19 +1007,7 @@ export async function validateCatalogSnapshot(snapshotDirectory) {
         throw new Error(`Invalid catalog snapshot root layout: missing [${missing.join(', ')}], unexpected [${unexpected.join(', ')}].`);
     }
     if (entries.includes(GENERATED_OUTPUT_MARKER_FILENAME)) {
-        const marker = await readRegularJson(path.join(rootDir, GENERATED_OUTPUT_MARKER_FILENAME), 'Catalog generated output marker');
-        const digestPattern = /^sha256:[0-9a-f]{64}$/u;
-        if (!isDeepStrictEqual(Object.keys(marker).sort(), [
-            'kind', 'schemaVersion', 'sourceIdentity', 'workspaceIdentity',
-        ])
-            || marker.schemaVersion !== 1
-            || marker.kind !== 'catalog'
-            || typeof marker.workspaceIdentity !== 'string'
-            || marker.workspaceIdentity.trim().length === 0
-            || typeof marker.sourceIdentity !== 'string'
-            || !digestPattern.test(marker.sourceIdentity)) {
-            throw new Error('Invalid catalog generated output marker.');
-        }
+        validateCatalogGeneratedOutputMarker(await readRegularJson(path.join(rootDir, GENERATED_OUTPUT_MARKER_FILENAME), 'Catalog generated output marker'));
     }
     const assertLayout = async (directory, expected) => {
         const real = await assertDirectoryWithoutSymlinks(directory, 'Catalog snapshot directory');
@@ -876,16 +1025,118 @@ 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 manifest = normalizeCatalogManifestV7(await readRegularJson(path.join(rootDir, CATALOG_MANIFEST_FILENAME), 'Catalog manifest v7'));
+    const normalizedEntries = manifest.entries;
+    const marketplaceIdentity = manifest.marketplace;
+    const pluginNames = normalizedEntries.map((entry) => entry.name);
+    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 platformEntries = {
+        claude: [],
+        codex: [],
+    };
+    for (const [index, name] of pluginNames.entries()) {
+        const pluginRoot = path.join(rootDir, 'plugins', name);
+        await assertDirectoryWithoutSymlinks(pluginRoot, `Catalog plugin ${JSON.stringify(name)}`);
+        const entry = normalizedEntries[index];
+        const rawBundleManifest = await readRegularJson(path.join(pluginRoot, SOURCE_MANIFEST_PATH), `Catalog plugin ${JSON.stringify(name)} bundle manifest`);
+        const digests = await calculateEntryDigests(pluginRoot);
+        const expectedDigests = {
+            artifactDigest: digests.artifactDigest,
+            manifestDigest: sha256(normalizeManifestDigestInput(rawBundleManifest)),
+            contentDigest: digests.contentDigest,
+        };
+        for (const field of Object.keys(expectedDigests)) {
+            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) {
+                await readRegularJson(platformManifest, `${platform} plugin manifest`);
+                platformEntries[platform].push(entry);
+            }
+        }
+    }
+    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 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,
+        plugins: platformEntries[platform].map(marketplaceEntry),
+    });
+    const expectedAgents = expectedMarketplace('codex');
+    const expectedClaude = expectedMarketplace('claude');
+    const normalizeMarketplaceOrder = (marketplace) => {
+        const canonical = JSON.parse(JSON.stringify(marketplace));
+        return {
+            ...canonical,
+            plugins: Array.isArray(canonical.plugins)
+                ? [...canonical.plugins].sort((left, right) => String(left?.name).localeCompare(String(right?.name)))
+                : canonical.plugins,
+        };
+    };
+    if (!isDeepStrictEqual(normalizeMarketplaceOrder(agentsMarketplace), normalizeMarketplaceOrder(expectedAgents))) {
+        throw new Error('Codex marketplace metadata or plugin inventory does not match the snapshot bundles.');
+    }
+    if (!isDeepStrictEqual(normalizeMarketplaceOrder(claudeMarketplace), normalizeMarketplaceOrder(expectedClaude))) {
+        throw new Error('Claude marketplace metadata or plugin inventory does not match the snapshot bundles.');
+    }
+    return { rootDir, manifest, snapshotDigest };
+}
+function validateCatalogGeneratedOutputMarker(raw) {
+    const marker = raw;
+    const digestPattern = /^sha256:[0-9a-f]{64}$/u;
+    if (!marker
+        || typeof marker !== 'object'
+        || Array.isArray(marker)
+        || !isDeepStrictEqual(Object.keys(marker).sort(), [
+            'kind', 'schemaVersion', 'sourceIdentity', 'workspaceIdentity',
+        ])
+        || marker.schemaVersion !== 1
+        || marker.kind !== 'catalog'
+        || typeof marker.workspaceIdentity !== 'string'
+        || marker.workspaceIdentity.trim().length === 0
+        || typeof marker.sourceIdentity !== 'string'
+        || !digestPattern.test(marker.sourceIdentity)) {
+        throw new Error('Invalid catalog generated output marker.');
+    }
+    return {
+        workspaceIdentity: marker.workspaceIdentity,
+        sourceIdentity: marker.sourceIdentity,
+    };
+}
+function normalizeCatalogManifestV7(rawValue) {
+    if (!rawValue || typeof rawValue !== 'object' || Array.isArray(rawValue)) {
+        throw new Error('Invalid catalog manifest v7: expected an object.');
+    }
+    const raw = rawValue;
     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 !== 7)
+        throw new Error('Invalid catalog manifest schemaVersion: expected 7.');
+    const base = normalizeCatalogManifestBase(raw, 'catalog manifest v7');
+    if (!(base.requires.aw.capabilities ?? []).includes('aw.catalog-snapshot.v7')) {
+        throw new Error('Invalid catalog manifest requires.aw.capabilities: expected aw.catalog-snapshot.v7.');
+    }
     const marketplaceIdentity = normalizeCatalogMarketplaceIdentity(raw.marketplace);
     if (!Array.isArray(raw.entries))
         throw new Error('Invalid catalog manifest entries: expected an array.');
@@ -901,94 +1152,84 @@ 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 v7')
         .map((entry, index) => ({ ...entry, contentDigest: contentDigests[index] }));
     const pluginNames = normalizedEntries.map((entry, index) => {
         if (typeof entry.name !== 'string')
             throw new Error(`Invalid catalog manifest entries[${index}].name.`);
+        if (entry.source !== `./plugins/${entry.name}`) {
+            throw new Error(`Catalog entry source for ${JSON.stringify(entry.name)} does not match its plugin bundle.`);
+        }
         return entry.name;
     });
     if (new Set(pluginNames).size !== pluginNames.length)
         throw new Error('Invalid catalog manifest entries: duplicate plugin name.');
     if (pluginNames.join('\0') !== [...pluginNames].sort().join('\0'))
         throw new Error('Invalid catalog manifest entries: expected stable name order.');
-    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 release = normalizeCatalogRelease(raw.release);
+    return {
+        schemaVersion: 7,
+        catalogVersion: base.catalogVersion,
+        channel: base.channel,
+        requires: base.requires,
+        marketplace: marketplaceIdentity,
+        release,
+        entries: normalizedEntries,
+    };
+}
+export async function validatePublishedCatalogSnapshotMetadata(snapshotDirectory) {
+    const rootDir = await assertDirectoryWithoutSymlinks(snapshotDirectory, 'Catalog snapshot metadata');
+    const [marker, manifest] = await Promise.all([
+        readRegularJson(path.join(rootDir, GENERATED_OUTPUT_MARKER_FILENAME), 'Catalog generated output marker').then(validateCatalogGeneratedOutputMarker),
+        readRegularJson(path.join(rootDir, CATALOG_MANIFEST_FILENAME), 'Catalog manifest v7').then(normalizeCatalogManifestV7),
+    ]);
+    if (manifest.release.state !== 'published') {
+        throw new Error('Published Catalog snapshot must have release.state published.');
+    }
+    return { rootDir, workspaceIdentity: marker.workspaceIdentity, manifest };
+}
+export async function validateCatalogSnapshotTransport(snapshotDirectory) {
+    return validateCatalogSnapshotTransportInternal(snapshotDirectory);
+}
+async function validateCatalogPluginEntriesComplete(validation, pluginNames) {
+    const entriesByName = new Map(validation.manifest.entries.map((entry) => [entry.name, entry]));
     const plugins = [];
-    for (const [index, name] of pluginNames.entries()) {
-        const pluginRoot = path.join(rootDir, 'plugins', name);
+    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 platformManifest = path.join(pluginRoot, `.${platform}-plugin`, 'plugin.json');
-            const exists = await fs.pathExists(platformManifest);
+            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(name)} has an inconsistent ${platform} bundle projection.`);
+                throw new Error(`Catalog plugin ${JSON.stringify(entry.name)} has an inconsistent ${platform} bundle projection.`);
             }
             if (exists) {
-                const rawPlatformManifest = await readRegularJson(platformManifest, `${platform} plugin manifest`);
+                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(normalizedEntries[index][field], expected[field])) {
-                throw new Error(`Catalog entry ${field} for ${JSON.stringify(name)} does not match its plugin bundle.`);
+            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);
-    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 = {
-        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')));
-    const normalizeMarketplaceOrder = (marketplace) => {
-        const canonical = JSON.parse(JSON.stringify(marketplace));
-        return {
-            ...canonical,
-            plugins: Array.isArray(canonical.plugins)
-                ? [...canonical.plugins].sort((left, right) => String(left?.name).localeCompare(String(right?.name)))
-                : canonical.plugins,
-        };
-    };
-    if (!isDeepStrictEqual(normalizeMarketplaceOrder(agentsMarketplace), normalizeMarketplaceOrder(expectedAgents))) {
-        throw new Error('Codex marketplace metadata or plugin inventory does not match the snapshot bundles.');
-    }
-    if (!isDeepStrictEqual(normalizeMarketplaceOrder(claudeMarketplace), normalizeMarketplaceOrder(expectedClaude))) {
-        throw new Error('Claude marketplace metadata or plugin inventory does not match the snapshot bundles.');
-    }
-    const release = normalizeCatalogRelease(raw.release, base.catalogVersion);
-    const manifest = {
-        schemaVersion: 4,
-        catalogVersion: base.catalogVersion,
-        channel: base.channel,
-        compatibility: base.compatibility,
-        marketplace: marketplaceIdentity,
-        release,
-        entries: normalizedEntries,
-    };
-    if (release.state === 'published') {
-        const contentDigest = publishedContentDigest(manifest);
-        if (release.contentDigest !== contentDigest) {
-            throw new Error('Published catalog release contentDigest does not match the snapshot.');
-        }
-    }
-    const hasLedger = entries.includes(PLUGIN_RELEASE_LEDGER_FILENAME);
-    if (release.state === 'published' && !hasLedger) {
-        throw new Error('Published Catalog snapshot must include plugin-release-ledger.json.');
-    }
-    if (release.state === 'development' && hasLedger) {
-        throw new Error('Development Catalog snapshot must not include plugin-release-ledger.json.');
-    }
-    const ledger = hasLedger
-        ? validatePluginReleaseLedgerAgainstManifest(await readRegularJson(path.join(rootDir, PLUGIN_RELEASE_LEDGER_FILENAME), 'Plugin release ledger'), manifest)
-        : undefined;
-    return { rootDir, manifest, ...(ledger ? { ledger } : {}), snapshotDigest };
+}
+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