release-skill 0.9.3 → 0.9.5

package/src/commands/ship.mjs

@@ -15,11 +15,92 @@ import {
 } from './post-release-local.mjs';
 import {
   ReleaseError,
+  CONFIG_INVALID,
   GATE_FAILED,
   PLAN_DIGEST_MISMATCH,
   CONSUMER_VERIFICATION_DEFERRED,
 } from '../core/errors.mjs';
 
+function normalizeNewShipUnitIds(releaseUnits, requestedUnitIds) {
+  if (requestedUnitIds === undefined) return undefined;
+  const availableUnitIds = (releaseUnits ?? []).map((unit) => unit.id);
+  if (!Array.isArray(requestedUnitIds) || requestedUnitIds.length === 0) {
+    throw new ReleaseError(
+      CONFIG_INVALID,
+      'explicit ship release-unit selection must contain at least one unit id',
+      { requestedUnitIds, availableUnitIds },
+    );
+  }
+  const requestedSet = new Set(requestedUnitIds);
+  const invalid = requestedUnitIds.filter((unitId) => typeof unitId !== 'string' || unitId.length === 0);
+  const unknown = requestedUnitIds.filter((unitId) => !availableUnitIds.includes(unitId));
+  if (invalid.length > 0 || requestedSet.size !== requestedUnitIds.length || unknown.length > 0) {
+    throw new ReleaseError(
+      CONFIG_INVALID,
+      'ship release-unit selection contains empty, duplicate, or unknown unit ids',
+      { requestedUnitIds, availableUnitIds },
+    );
+  }
+  return availableUnitIds.filter((unitId) => requestedSet.has(unitId));
+}
+
+function sameUnitSelection(left, right) {
+  return Array.isArray(left)
+    && Array.isArray(right)
+    && left.length === right.length
+    && new Set(left).size === left.length
+    && new Set(right).size === right.length
+    && left.every((unitId) => right.includes(unitId));
+}
+
+function sameUnitOrder(left, right) {
+  return Array.isArray(left)
+    && Array.isArray(right)
+    && left.length === right.length
+    && left.every((unitId, index) => unitId === right[index]);
+}
+
+function unitScopeMismatch(statePath, stateUnitIds, requestedUnitIds, message) {
+  return new ReleaseError(
+    GATE_FAILED,
+    message,
+    {
+      reason: 'SHIP_STATE_UNIT_SCOPE_MISMATCH',
+      statePath,
+      stateUnitIds: stateUnitIds ?? null,
+      requestedUnitIds: requestedUnitIds ?? null,
+    },
+  );
+}
+
+function assertFrozenPlanUnitScope({ statePath, stateUnitIds, expectedUnitIds, plan }) {
+  const planUnitIds = (plan.units ?? []).map((unit) => unit.id);
+  const exactMatch = Array.isArray(expectedUnitIds)
+    && planUnitIds.length === expectedUnitIds.length
+    && planUnitIds.every((unitId, index) => unitId === expectedUnitIds[index]);
+  if (!exactMatch) {
+    throw unitScopeMismatch(
+      statePath,
+      stateUnitIds,
+      planUnitIds,
+      'ship state release-unit scope does not match frozen plan.units',
+    );
+  }
+}
+
+async function readFrozenPlanForUnitScope(planPath, statePath, stateUnitIds) {
+  try {
+    return JSON.parse(await readFile(planPath, 'utf8'));
+  } catch (error) {
+    throw unitScopeMismatch(
+      statePath,
+      stateUnitIds,
+      null,
+      `cannot verify ship state release-unit scope against frozen plan: ${error.message}`,
+    );
+  }
+}
+
 async function writeJsonAtomic(path, value) {
   await mkdir(dirname(path), { recursive: true });
   const { stateDigest: _oldDigest, ...body } = value;
@@ -93,7 +174,8 @@ async function defaultDependencies() {
   };
 }
 
-function publicState(state) {
+function publicState(state, { postRelease } = {}) {
+  const visiblePostRelease = postRelease === undefined ? state.postRelease : postRelease;
   return {
     command: 'ship',
     status: state.status,
@@ -102,6 +184,7 @@ function publicState(state) {
     ...(state.hooks && state.hooks.length > 0 ? {
       hooks: state.hooks,
     } : {}),
+    ...(state.selectedUnitIds ? { selectedUnitIds: state.selectedUnitIds } : {}),
     ...(state.planPath ? {
       planPath: state.planPath,
       planDigest: state.planDigest,
@@ -117,7 +200,7 @@ function publicState(state) {
     ...(state.requirements ? { requirements: state.requirements } : {}),
     ...(state.manualFollowUps ? { manualFollowUps: state.manualFollowUps } : {}),
     ...(state.metadataUpdate ? { metadataUpdate: state.metadataUpdate } : {}),
-    ...(state.postRelease ? { postRelease: state.postRelease } : {}),
+    ...(visiblePostRelease ? { postRelease: visiblePostRelease } : {}),
     externalActionsIncludedInPlanApproval: true,
     verificationGatesIncludedInPlanApproval: true,
     postPublishCheckpointApprovalsIncludedInPlanApproval: false,
@@ -334,6 +417,24 @@ export async function advanceShip(options = {}, injected = {}) {
       );
     }
   }
+  if (state && options.unitIds !== undefined) {
+    if (!Array.isArray(state.selectedUnitIds)) {
+      throw unitScopeMismatch(
+        statePath,
+        null,
+        options.unitIds,
+        'an existing full-scope or legacy ship state cannot acquire --unit; provide a new --state path',
+      );
+    }
+    if (!sameUnitSelection(state.selectedUnitIds, options.unitIds)) {
+      throw unitScopeMismatch(
+        statePath,
+        state.selectedUnitIds,
+        options.unitIds,
+        'ship state release-unit scope does not match the requested --unit values',
+      );
+    }
+  }
   if (state?.gitTransport) {
     process.env.RELEASE_SKILL_GIT_TRANSPORT = state.gitTransport;
   }
@@ -341,6 +442,7 @@ export async function advanceShip(options = {}, injected = {}) {
   if (!state) {
     const loaded = await deps.loadProjectConfig({ root });
     const hooks = Object.keys(loaded.config.hooks ?? {}).sort();
+    const selectedUnitIds = normalizeNewShipUnitIds(loaded.config.releaseUnits, options.unitIds);
     state = {
       schemaVersion: 2,
       root,
@@ -348,6 +450,7 @@ export async function advanceShip(options = {}, injected = {}) {
       targetVersion: options.targetVersion ?? null,
       configDigest: loaded.configDigest,
       hooks,
+      ...(selectedUnitIds ? { selectedUnitIds } : {}),
       status: 'NEW',
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString(),
@@ -364,8 +467,53 @@ export async function advanceShip(options = {}, injected = {}) {
     await writeJsonAtomic(statePath, state);
   }
 
+  if (state.planPath && Array.isArray(state.selectedUnitIds)) {
+    const frozenPlan = await readFrozenPlanForUnitScope(
+      state.planPath,
+      statePath,
+      state.selectedUnitIds,
+    );
+    assertFrozenPlanUnitScope({
+      statePath,
+      stateUnitIds: state.selectedUnitIds,
+      expectedUnitIds: state.selectedUnitIds,
+      plan: frozenPlan,
+    });
+  }
+
   if (state.status === 'NEW') {
     const loaded = await deps.loadProjectConfig({ root });
+    let stateChanged = false;
+    if (Array.isArray(state.selectedUnitIds)) {
+      const normalizedStateUnitIds = normalizeNewShipUnitIds(
+        loaded.config.releaseUnits,
+        state.selectedUnitIds,
+      );
+      if (!sameUnitSelection(normalizedStateUnitIds, state.selectedUnitIds)) {
+        throw unitScopeMismatch(
+          statePath,
+          state.selectedUnitIds,
+          normalizedStateUnitIds,
+          'ship state release-unit scope no longer matches project configuration',
+        );
+      }
+      if (!sameUnitOrder(normalizedStateUnitIds, state.selectedUnitIds)) {
+        if (state.planPath) {
+          throw unitScopeMismatch(
+            statePath,
+            state.selectedUnitIds,
+            normalizedStateUnitIds,
+            'frozen ship state release-unit order no longer matches project configuration',
+          );
+        }
+        state = {
+          ...state,
+          selectedUnitIds: normalizedStateUnitIds,
+          updatedAt: new Date().toISOString(),
+        };
+        stateChanged = true;
+      }
+    }
     if (loaded.configDigest !== state.configDigest) {
       const hooks = Object.keys(loaded.config.hooks ?? {}).sort();
       state = {
@@ -375,8 +523,9 @@ export async function advanceShip(options = {}, injected = {}) {
         status: 'NEW',
         updatedAt: new Date().toISOString(),
       };
-      await writeJsonAtomic(statePath, state);
+      stateChanged = true;
     }
+    if (stateChanged) await writeJsonAtomic(statePath, state);
     const prepared = await deps.prepareRelease({
       root,
       version: state.targetVersion ?? undefined,
@@ -385,10 +534,24 @@ export async function advanceShip(options = {}, injected = {}) {
       hooksAuthorized: true,
       verificationGatesAuthorized: true,
       hookCache: true,
+      ...(state.selectedUnitIds ? { unitIds: state.selectedUnitIds } : {}),
     });
+    let frozenPlan = null;
+    if (Array.isArray(state.selectedUnitIds) || deps.preflightGitTransports) {
+      frozenPlan = Array.isArray(state.selectedUnitIds)
+        ? await readFrozenPlanForUnitScope(prepared.planPath, statePath, state.selectedUnitIds)
+        : JSON.parse(await readFile(prepared.planPath, 'utf8'));
+    }
+    if (Array.isArray(state.selectedUnitIds)) {
+      assertFrozenPlanUnitScope({
+        statePath,
+        stateUnitIds: state.selectedUnitIds,
+        expectedUnitIds: state.selectedUnitIds,
+        plan: frozenPlan,
+      });
+    }
     let transportPreflight = null;
     if (deps.preflightGitTransports) {
-      const frozenPlan = JSON.parse(await readFile(prepared.planPath, 'utf8'));
       transportPreflight = await deps.preflightGitTransports(frozenPlan);
       process.env.RELEASE_SKILL_GIT_TRANSPORT = transportPreflight.transport;
     }
@@ -556,15 +719,6 @@ export async function advanceShip(options = {}, injected = {}) {
         updatedAt: new Date().toISOString(),
       };
       await writeJsonAtomic(statePath, state);
-      if (verified.status === 'VERIFIED') {
-        try {
-          state.postRelease = derivePostReleaseChecklist(plan);
-        } catch (error) {
-          state.postRelease = unavailablePostReleaseChecklist(plan, error);
-        }
-        state.updatedAt = new Date().toISOString();
-        await writeJsonAtomic(statePath, state);
-      }
     } catch (error) {
       if (error?.code !== CONSUMER_VERIFICATION_DEFERRED) throw error;
       state = {
@@ -673,5 +827,28 @@ export async function advanceShip(options = {}, injected = {}) {
     }
   }
 
+  if (state.status === 'VERIFIED') {
+    const finalPlan = JSON.parse(await readFile(state.planPath, 'utf8'));
+    const hasPostVerify = normalizePostPublishView(finalPlan).some((declaration) => (
+      (declaration.hooks ?? []).some((hook) => hook.phase === 'postVerify')
+    ));
+    const localFinishRunPath = hasPostVerify
+      ? (state.postVerify?.status === 'DISTRIBUTED' ? state.postVerify.runPath : undefined)
+      : state.verifyRunPath;
+    let postRelease;
+    try {
+      postRelease = derivePostReleaseChecklist(finalPlan, {
+        root,
+        statePath,
+        unitIds: state.selectedUnitIds,
+        runPath: localFinishRunPath,
+        postVerifyComplete: !hasPostVerify || state.postVerify?.status === 'DISTRIBUTED',
+      });
+    } catch (error) {
+      postRelease = unavailablePostReleaseChecklist(finalPlan, error);
+    }
+    return publicState(state, { postRelease });
+  }
+
   return publicState(state);
 }

package/src/commands/verify.mjs

@@ -68,6 +68,7 @@ import {
   verifyFrozenPluginWithFoundation,
 } from '../core/foundation-plugin-verification.mjs';
 import { resolveUnitScopedPath } from '../snapshot/public-path.mjs';
+import { canonicalJson } from '../core/digest.mjs';
 import {
   normalizeRegistry,
   registryTokenKey,
@@ -83,7 +84,7 @@ import {
 } from '../core/skill-resource-closure.mjs';
 import { deriveSurfaceHostBinding, pluginRootFromManifestRelativePath } from '../core/surface-host-bindings.mjs';
 import { isRemoteWriteAction, isMarketplaceAction } from '../core/checkpoints.mjs';
-import { PLATFORMS, normalizeHostId } from '../platforms/registry.mjs';
+import { PLATFORMS, normalizeHostId, projectObservedStandaloneIndexInstallIdentity } from '../platforms/registry.mjs';
 import {
   shouldSkipVerification,
   INSTALLATION_CONTRACT_ALGORITHM_VERSION,
@@ -183,6 +184,140 @@ function defaultClock() {
   return new Date().toISOString();
 }
 
+const FIRST_RELEASE_BOOTSTRAP_MODE = 'manual-index-checkpoint';
+const EXTERNAL_MARKETPLACE_SHA_RE = /^[0-9a-f]{40}$/;
+
+function parseMarketplaceHead(stdout) {
+  if (typeof stdout !== 'string') return null;
+  let sha = null;
+  let defaultBranch = null;
+  for (const line of stdout.trim().split('\n').filter(Boolean)) {
+    const tab = line.indexOf('\t');
+    if (tab < 0) continue;
+    const left = line.slice(0, tab);
+    const right = line.slice(tab + 1);
+    if (right !== 'HEAD') continue;
+    if (left.startsWith('ref: refs/heads/')) defaultBranch = left.slice('ref: refs/heads/'.length);
+    else if (EXTERNAL_MARKETPLACE_SHA_RE.test(left)) sha = left;
+  }
+  return sha && defaultBranch ? { sha, defaultBranch } : null;
+}
+
+async function defaultObserveMarketplaceHead(repo, { githubHost = 'github.com' } = {}) {
+  try {
+    const { stdout } = await execFile('git', [
+      'ls-remote', '--symref', `https://${githubHost}/${repo}.git`, 'HEAD',
+    ], { shell: false, encoding: 'utf8', timeout: 30000 });
+    const parsed = parseMarketplaceHead(stdout);
+    return parsed ? { status: 'observed', ...parsed } : { status: 'unknown', error: 'could not resolve marketplace HEAD' };
+  } catch (error) {
+    return { status: 'unknown', error: error.message };
+  }
+}
+
+function decodeMarketplaceIndex(content) {
+  if (typeof content !== 'string') return null;
+  try {
+    return JSON.parse(Buffer.from(content.replace(/\s/g, ''), 'base64').toString('utf8'));
+  } catch {
+    return null;
+  }
+}
+
+async function defaultFetchMarketplaceIndex(repo, path, ref, { githubHost = 'github.com' } = {}) {
+  try {
+    const { stdout } = await execFile('gh', [
+      'api', `repos/${repo}/contents/${path}?ref=${ref}`, '--jq', '.content',
+    ], {
+      shell: false,
+      encoding: 'utf8',
+      timeout: 30000,
+      env: { ...process.env, GH_HOST: githubHost },
+    });
+    const index = decodeMarketplaceIndex(stdout);
+    return index && typeof index === 'object'
+      ? { status: 'fetched', index }
+      : { status: 'unknown', error: 'could not decode marketplace index' };
+  } catch (error) {
+    return { status: 'unknown', error: error.message };
+  }
+}
+
+async function verifyFirstReleaseBootstrapIndexes({
+  actions,
+  plan,
+  evidence,
+  observeHeadFn,
+  fetchIndexFn,
+}) {
+  const bindings = new Map();
+  for (const action of actions) {
+    if (action.parameters?.firstReleaseBootstrap !== FIRST_RELEASE_BOOTSTRAP_MODE) continue;
+    const params = action.parameters;
+    const githubHost = params.githubHost ?? 'github.com';
+    const failDeferred = async (reason, observed = null) => {
+      await evidence.append({
+        phase: 'verify-marketplace-bootstrap-index',
+        actionId: action.id,
+        actionType: action.type,
+        status: 'needs-input',
+        reason,
+        ...(observed ? { observed } : {}),
+      });
+      throw new ReleaseError(
+        CONSUMER_VERIFICATION_DEFERRED,
+        `first-release bootstrap marketplace index is not an exact match for action "${action.id}"; complete the manual index checkpoint and retry verify with the same plan`,
+        { actionId: action.id, reason, observed, nextState: 'NEEDS_MANUAL_ATTESTATIONS' },
+      );
+    };
+    const observed = await observeHeadFn(params.repo, { githubHost });
+    if (observed?.status !== 'observed' || !EXTERNAL_MARKETPLACE_SHA_RE.test(observed.sha ?? '') || !observed.defaultBranch) {
+      await failDeferred(`could not observe current marketplace HEAD: ${observed?.error ?? 'unknown'}`, observed);
+    }
+    const path = params.marketplaceIndexPath;
+    const fetched = await fetchIndexFn(params.repo, path, observed.sha, { githubHost });
+    if (fetched?.status !== 'fetched' || !fetched.index || typeof fetched.index !== 'object') {
+      await failDeferred(`could not read marketplace index at ${observed.sha}: ${fetched?.error ?? 'unknown'}`, observed);
+    }
+    const index = fetched.index;
+    if (index.name !== params.marketplaceName) {
+      await failDeferred(`marketplace name mismatch: expected ${params.marketplaceName}, got ${index.name}`, { ...observed, name: index.name });
+    }
+    if (!Array.isArray(index.plugins)) {
+      await failDeferred('marketplace index plugins must be an array', { ...observed, pluginsType: typeof index.plugins });
+    }
+    const entries = index.plugins.filter((entry) => entry && entry.name === params.plugin);
+    let projectedEntry = null;
+    if (entries.length === 1) {
+      try {
+        projectedEntry = projectObservedStandaloneIndexInstallIdentity(params.consumer, entries[0]);
+      } catch {
+        projectedEntry = null;
+      }
+    }
+    if (entries.length !== 1 || !projectedEntry || canonicalJson(projectedEntry) !== canonicalJson(params.selectedEntry)) {
+      await failDeferred('marketplace selectedEntry is missing, duplicated, or does not exactly match the plan-bound expected entry', {
+        ...observed,
+        entryCount: entries.length,
+        selectedEntry: projectedEntry ?? entries[0] ?? null,
+      });
+    }
+    bindings.set(action.id, {
+      marketplaceIndexSha: observed.sha,
+      marketplaceIndexRef: action.type === 'claude-marketplace-install' ? observed.defaultBranch : observed.sha,
+    });
+    await evidence.append({
+      phase: 'verify-marketplace-bootstrap-index',
+      actionId: action.id,
+      actionType: action.type,
+      status: 'observed',
+      marketplaceIndexSha: observed.sha,
+      marketplaceIndexRef: action.type === 'claude-marketplace-install' ? observed.defaultBranch : observed.sha,
+    });
+  }
+  return bindings;
+}
+
 /**
  * 验证摘要格式是否为合法的 64 位十六进制字符串。
  *
@@ -957,6 +1092,8 @@ export async function verifyRelease(options) {
     execFn,
     configPath: configPathOpt,
     runPluginVerificationFn,
+    observeFirstReleaseMarketplaceHeadFn,
+    fetchFirstReleaseMarketplaceIndexFn,
   } = options ?? {};
 
   const clockFn = typeof clockOpt === 'function' ? clockOpt : defaultClock;
@@ -1265,6 +1402,19 @@ export async function verifyRelease(options) {
     const consumerVerificationReceipts = [];
     const actions = plan.externalActions ?? [];
 
+    // A bootstrap plan intentionally leaves the final marketplace index SHA
+    // pending. Before any marketplace adapter call, observe the current
+    // remote index and require an exact match for the plan-bound entry. A
+    // mismatch is the existing deferred/manual-attestation state; no add or
+    // install command is reached on this path.
+    const bootstrapIndexBindings = await verifyFirstReleaseBootstrapIndexes({
+      actions,
+      plan,
+      evidence,
+      observeHeadFn: observeFirstReleaseMarketplaceHeadFn ?? defaultObserveMarketplaceHead,
+      fetchIndexFn: fetchFirstReleaseMarketplaceIndexFn ?? defaultFetchMarketplaceIndex,
+    });
+
     // --- 自动发现可信消费端验证收据 ---
     // 收据选择逻辑（per-action 从所有候选中选最新匹配）：
     // - 只读取同一权威 .release-skill/runs 的真实直接子目录
@@ -1533,10 +1683,21 @@ export async function verifyRelease(options) {
           runDir,
         };
 
+        const bootstrapBinding = bootstrapIndexBindings.get(action.id) ?? null;
         const actionInput = {
           actionType: adapterActionType,
           ...action.parameters,
         };
+        if (bootstrapBinding) {
+          actionInput.marketplaceCommitSha = bootstrapBinding.marketplaceIndexSha;
+          actionInput.marketplaceIndexSha = bootstrapBinding.marketplaceIndexSha;
+          actionInput.ref = bootstrapBinding.marketplaceIndexRef;
+          actionInput.sourceDescriptor = {
+            ...actionInput.sourceDescriptor,
+            marketplaceCommitSha: bootstrapBinding.marketplaceIndexSha,
+            ref: bootstrapBinding.marketplaceIndexRef,
+          };
+        }
 
         // --- 安装契约摘要免验检查 ---
         // 从计划中读取冻结的安装契约摘要。
@@ -1614,6 +1775,7 @@ export async function verifyRelease(options) {
               actionType: action.type,
               status: VERIFICATION_RESOLVED_TYPES.NOT_REQUIRED_UNCHANGED,
               installationContractDigest: currentDigest,
+              ...(bootstrapBinding ? { marketplaceIndexSha: bootstrapBinding.marketplaceIndexSha, marketplaceIndexRef: bootstrapBinding.marketplaceIndexRef } : {}),
               reason: '安装契约摘要未变化，跳过验证',
             });
 
@@ -1634,6 +1796,7 @@ export async function verifyRelease(options) {
               actionType: action.type,
               status: VERIFICATION_RESOLVED_TYPES.NOT_REQUIRED_UNCHANGED,
               installationContractDigest: currentDigest,
+              ...(bootstrapBinding ? { marketplaceIndexSha: bootstrapBinding.marketplaceIndexSha, marketplaceIndexRef: bootstrapBinding.marketplaceIndexRef } : {}),
             });
 
             return;
@@ -1657,8 +1820,16 @@ export async function verifyRelease(options) {
         }
 
         // Step 3c: Verify (observe + match against plan expected state)
+        const expectedInput = bootstrapBinding
+          ? {
+            ...action.expected,
+            marketplaceCommitSha: bootstrapBinding.marketplaceIndexSha,
+            marketplaceIndexSha: bootstrapBinding.marketplaceIndexSha,
+            ref: bootstrapBinding.marketplaceIndexRef,
+          }
+          : action.expected;
         const verifyResult = await adapter.verify(
-          { ...actionInput, expected: action.expected },
+          { ...actionInput, expected: expectedInput },
           marketplaceContext,
         );
 
@@ -1676,6 +1847,7 @@ export async function verifyRelease(options) {
           status: resolvedStatus,
           observation: verifyResult.observation,
           error: verifyResult.error,
+          ...(bootstrapBinding ? { marketplaceIndexSha: bootstrapBinding.marketplaceIndexSha, marketplaceIndexRef: bootstrapBinding.marketplaceIndexRef } : {}),
           ...(dist?.installationContractDigest ? { installationContractDigest: dist.installationContractDigest } : {}),
         };
         adapterChecks.push(check);
@@ -1700,6 +1872,7 @@ export async function verifyRelease(options) {
           actionId: action.id,
           actionType: action.type,
           status: check.status,
+          ...(bootstrapBinding ? { marketplaceIndexSha: bootstrapBinding.marketplaceIndexSha, marketplaceIndexRef: bootstrapBinding.marketplaceIndexRef } : {}),
         });
 
         if (check.status === 'FAILED') {

package/src/core/foundation-plugin-verification.mjs

@@ -33,7 +33,6 @@ import { ReleaseError, POST_PUBLISH_VERIFY_FAILED } from './errors.mjs';
 // this value so an upstream contract change fails closed during adoption.
 const FOUNDATION_PLUGIN_DRIVER_VERSION = '1.0.0';
 const SHA256_PATTERN = /^[0-9a-f]{64}$/u;
-const BASE64_PATTERN = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u;
 
 function isSafeRelativePath(value) {
   return typeof value === 'string'
@@ -46,7 +45,28 @@ function isSafeRelativePath(value) {
 }
 
 function decodeCanonicalBase64(value) {
-  if (typeof value !== 'string' || !BASE64_PATTERN.test(value)) return null;
+  if (typeof value !== 'string' || value.length % 4 !== 0) return null;
+  let paddingStart = -1;
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code === 61) {
+      if (paddingStart === -1) paddingStart = index;
+      continue;
+    }
+    if (paddingStart !== -1 || !(
+      code >= 65 && code <= 90
+      || code >= 97 && code <= 122
+      || code >= 48 && code <= 57
+      || code === 43
+      || code === 47
+    )) return null;
+  }
+  if (
+    paddingStart !== -1
+    && value.length - paddingStart > 2
+    || paddingStart !== -1
+    && paddingStart % 4 < 2
+  ) return null;
   const decoded = Buffer.from(value, 'base64');
   return decoded.toString('base64') === value ? decoded : null;
 }

package/src/core/plan.mjs

@@ -34,7 +34,7 @@ import { digestReleaseAssetIdentities, normalizeReleaseAssets } from './release-
 // function bodies (after the import graph has settled), never at plan.mjs
 // module-init time — a top-level read would hit the registry's
 // not-yet-initialized bindings when the cycle is entered registry-first.
-import { PLATFORMS } from '../platforms/registry.mjs';
+import { PLATFORMS, buildExpectedStandaloneIndexInstallIdentity } from '../platforms/registry.mjs';
 
 // ---------------------------------------------------------------------------
 // Schema loaded from the authoritative JSON file (single source of truth)
@@ -1278,6 +1278,7 @@ export function validatePlanActionCompleteness(plan, options = {}) {
         // 也不得接受"用 null 表示存在"的方案。
         if (production && externalMarketplace && dist.marketplaceSourceType === 'standalone-index') {
           const params = action.parameters;
+          const bootstrap = dist.firstReleaseBootstrap === 'manual-index-checkpoint';
           if (params) {
             if (!params.marketplaceIndexPath) {
               failures.push(
@@ -1294,6 +1295,41 @@ export function validatePlanActionCompleteness(plan, options = {}) {
                 `unit "${unitId}", action "${action.id}": parameters.selectedEntry is required for production standalone-index`,
               );
             }
+            if (bootstrap) {
+              if (params.firstReleaseBootstrap !== 'manual-index-checkpoint') {
+                failures.push(
+                  `unit "${unitId}", action "${action.id}": parameters.firstReleaseBootstrap must be manual-index-checkpoint for a bootstrap distribution`,
+                );
+              }
+              if (params.marketplaceIndexSha !== null) {
+                failures.push(
+                  `unit "${unitId}", action "${action.id}": parameters.marketplaceIndexSha must remain null until the manual index checkpoint`,
+                );
+              }
+              let expectedEntry = null;
+              try {
+                expectedEntry = buildExpectedStandaloneIndexInstallIdentity(platform, {
+                  name: plugin,
+                  version: targetVersion,
+                  repo: publicRepo,
+                  tag: expectedTag,
+                  sha: frozen?.commit,
+                });
+              } catch {
+                // Missing frozen identity is reported by the surrounding
+                // production-field checks; do not turn completeness into an
+                // uncaught implementation error.
+              }
+              if (!expectedEntry || canonicalJson(params.selectedEntry) !== canonicalJson(expectedEntry)) {
+                failures.push(
+                  `unit "${unitId}", action "${action.id}": bootstrap selectedEntry does not match the frozen plugin repository, tag, commit, and version`,
+                );
+              }
+            } else if (params.firstReleaseBootstrap !== undefined || params.marketplaceIndexSha !== undefined) {
+              failures.push(
+                `unit "${unitId}", action "${action.id}": bootstrap-only fields are not allowed without firstReleaseBootstrap`,
+              );
+            }
           }
         }
 
@@ -1329,6 +1365,14 @@ export function validatePlanActionCompleteness(plan, options = {}) {
             _checkRequired(action, 'expected.ref', action.expected?.ref, action.parameters?.ref, unitId, failures);
             _checkRequired(action, 'expected.marketplaceLocation', action.expected?.marketplaceLocation, 'external', unitId, failures);
             _checkRequired(action, 'expected.marketplaceCommitSha', action.expected?.marketplaceCommitSha, action.parameters?.marketplaceCommitSha, unitId, failures);
+            if (dist.firstReleaseBootstrap === 'manual-index-checkpoint') {
+              _checkRequired(action, 'expected.firstReleaseBootstrap', action.expected?.firstReleaseBootstrap, 'manual-index-checkpoint', unitId, failures);
+              if (action.expected?.marketplaceIndexSha !== null) {
+                failures.push(
+                  `unit "${unitId}", action "${action.id}": expected.marketplaceIndexSha must be null until the manual index checkpoint`,
+                );
+              }
+            }
           } else {
             _checkRequired(action, 'expected.repo', action.expected?.repo, publicRepo, unitId, failures);
             _checkRequired(action, 'expected.ref', action.expected?.ref, expectedTag, unitId, failures);