release-skill 0.9.6 → 0.9.8

package/src/commands/verify.mjs

@@ -23,7 +23,11 @@ import { resolveContained } from 'skill-family-harness-node';
 const execFile = promisify(execFileCb);
 
 import { validatePlan, computePlanDigest, validatePlanActionCompleteness } from '../core/plan.mjs';
-import { normalizePostPublishView, postPublishActionId } from '../core/postpublish.mjs';
+import {
+  normalizePostPublishView,
+  postPublishActionId,
+  requiresPostPublishDistribution,
+} from '../core/postpublish.mjs';
 import { createEvidenceWriter } from '../core/evidence.mjs';
 import { readRunRecovery } from '../core/recovery.mjs';
 import {
@@ -1230,15 +1234,11 @@ export async function verifyRelease(options) {
 
     // =======================================================================
     // Step 2b: Check for postPublish distribution requirement.
-    // v0.6.3 R1: the gate triggers on targets OR hooks declarations, and a
-    // PARTIAL distribute run passes only through the blocksVerified:false
+    // The gate triggers only when targets or distribute-phase hooks exist.
+    // A PARTIAL distribute run passes only through the blocksVerified:false
     // exemption path (evaluateDistributeGateRun) — warned, never silent.
     // =======================================================================
-    // §4.3 unified normalization: v3 empty arrays mean no distribution
-    // requirement; legacy absent postPublish resolves to the same empty view.
-    const postPublishDeclarations = normalizePostPublishView(plan);
-    const requiresDistribution = postPublishDeclarations.some((declaration) =>
-      (declaration.targets?.length ?? 0) > 0 || (declaration.hooks?.length ?? 0) > 0);
+    const requiresDistribution = requiresPostPublishDistribution(plan);
     if (requiresDistribution) {
       await evidence.append({ phase: 'verify', step: 'distribute-run-discovery', status: 'started' });
 
@@ -2052,11 +2052,12 @@ export async function verifyRelease(options) {
       await evidence.append({ phase: 'verify', step: 'skill-resource-closure', status: 'started' });
 
       // Collect install paths from marketplace adapter checks.
-      // R-13 P2 (ruling 6): the surface binding is derived from the frozen
-      // installation contract at the REAL install coordinates — the same
-      // derivation rule prepare and publish use, never a hard-coded '.'.
-      // Plans without a frozen installation contract (legacy) fall back to
-      // the plugin-root surface ('.') with the legacy permissive checks.
+      // R-13 P2 (ruling 6): prepare and publish derive surface bindings in
+      // frozen snapshot-root coordinates. An adapter observation is already
+      // rooted at the installed plugin, so verify derives the same manifest
+      // skills fact relative to '.' at that consumer coordinate. Plans
+      // without a frozen installation contract (legacy) fall back to the
+      // plugin-root surface ('.') with the legacy permissive checks.
       const installSurfaces = [];
       for (const check of adapterChecks) {
         const platform = PLATFORMS.find((p) => p.actionType === check.actionType);
@@ -2065,11 +2066,16 @@ export async function verifyRelease(options) {
         const unit = (plan.units ?? []).find((u) => u.id === unitId);
         const dist = unit?.distributions?.find((d) => d.type === platform.distributionType);
         let binding = null;
+        let frozenPluginRoot = null;
         const contract = dist?.installationContract;
         if (contract?.normalizedManifest) {
+          frozenPluginRoot = pluginRootFromManifestRelativePath(contract.manifestRelativePath);
           binding = await deriveSurfaceHostBinding({
             manifest: contract.normalizedManifest,
-            pluginRoot: pluginRootFromManifestRelativePath(contract.manifestRelativePath),
+            // Adapter observations are already rooted at the installed
+            // plugin. The frozen manifest's skills path is therefore
+            // relative to '.', not to the snapshot-root manifest path.
+            pluginRoot: '.',
             platform,
             snapshotDir: check.observation.installPath,
           });
@@ -2082,6 +2088,7 @@ export async function verifyRelease(options) {
           unitId,
           surfaceId: binding?.surfaceId ?? '.',
           binding,
+          frozenPluginRoot,
           unit,
         });
       }
@@ -2192,7 +2199,7 @@ export async function verifyRelease(options) {
           // publish's recheck uses.
           const pluginDistCount = (surface.unit?.distributions ?? [])
             .filter((d) => d.type !== 'npm').length;
-          if (pluginDistCount === 1) {
+          if (pluginDistCount === 1 && surface.frozenPluginRoot === '.') {
             const observedReceipt = createSkillResourceClosureReceipt(closureResult, {
               unitId: surface.unitId,
               preparedAt: expectedUnitReceipt.preparedAt ?? null,

package/src/core/postpublish.mjs

@@ -547,6 +547,30 @@ export function normalizePostPublishView(plan) {
   );
 }
 
+/**
+ * Decide whether a frozen plan has work for the distribute phase.
+ *
+ * A declaration requires distribute when it contains at least one legacy
+ * target, an explicit phase:distribute hook, or a hook whose omitted phase
+ * keeps the existing distribute default. phase:postVerify hooks belong only
+ * to the independent postVerify run and must not allocate an empty
+ * distribute predecessor.
+ *
+ * This is the single release-domain authority used by ship, verify, and
+ * recovery. Shape compatibility remains owned by normalizePostPublishView.
+ *
+ * @param {object} plan - Frozen release plan.
+ * @returns {boolean} Whether distribute must precede verify.
+ */
+export function requiresPostPublishDistribution(plan) {
+  return normalizePostPublishView(plan).some((declaration) => (
+    (declaration.targets?.length ?? 0) > 0
+    || (declaration.hooks ?? []).some((hook) => (
+      hook.phase === undefined || hook.phase === 'distribute'
+    ))
+  ));
+}
+
 /**
  * Array-level domain validation: every EXPLICIT hooks[].id must be unique
  * across the whole declaration array (multi-release-unit postPublish v3,

package/src/core/recovery.mjs

@@ -33,7 +33,12 @@ import { validatePlan, computePlanDigest, assertImmutablePlanAuthority } from '.
 import { validateApproval, validateApprovalRecordSchema, assertImmutableApprovalAuthority, computeApprovalDigest } from './approval.mjs';
 import { isMarketplaceAction } from './checkpoints.mjs';
 import { ReleaseError, GATE_FAILED } from './errors.mjs';
-import { effectiveHookRequiresApproval, normalizePostPublishView, postPublishActionId } from './postpublish.mjs';
+import {
+  effectiveHookRequiresApproval,
+  normalizePostPublishView,
+  postPublishActionId,
+  requiresPostPublishDistribution,
+} from './postpublish.mjs';
 import { assertPostPublishApprovalAuthority, validatePostPublishApproval } from './postpublish-approval.mjs';
 
 /** Remote errors alone are insufficient to select a safe recovery phase. */
@@ -274,11 +279,8 @@ export async function readRunRecovery(runPath, options = {}) {
       }
     } else if (['publish', 'reconcile'].includes(command)) {
       if (run.status === 'PUBLISHED') {
-        // §4.3 unified normalization: v3 empty arrays mean no distribute work
-        // at all; only declarations carrying targets or hooks require the
-        // distribution phase.
-        const needsDistribution = normalizePostPublishView(plan).some((declaration) =>
-          (declaration.targets?.length ?? 0) > 0 || (declaration.hooks?.length ?? 0) > 0);
+        // phase:postVerify hooks do not create an empty distribute predecessor.
+        const needsDistribution = requiresPostPublishDistribution(plan);
         code = needsDistribution ? 'DISTRIBUTE' : 'VERIFY';
       } else if (run.status === 'PARTIAL') {
         code = 'RECONCILE';

package/src/core/skill-resource-closure.mjs

@@ -742,9 +742,27 @@ export async function checkSkillResourceClosure({
  * @param {Array<{ id: string, host: string, skillCount: number }>} surfaces
  * @returns {{ passed: boolean, missing: Array<{ host: string, skillCount: number }> }}
  */
-export function evaluateDeclaredHostSurfaceCoverage(expectedHosts, surfaces) {
+export function evaluateDeclaredHostSurfaceCoverage(expectedHosts, surfaces, coverageClaims = []) {
   const missing = [];
+  const observedById = new Map((surfaces ?? []).map((surface) => [surface.id, surface]));
+  const claimsByHost = new Map();
+  for (const claim of coverageClaims ?? []) {
+    const hostClaims = claimsByHost.get(claim.host) ?? [];
+    hostClaims.push(claim);
+    claimsByHost.set(claim.host, hostClaims);
+  }
   for (const expectedHost of [...new Set(expectedHosts ?? [])].sort((a, b) => a.localeCompare(b))) {
+    const declaredClaims = claimsByHost.get(expectedHost) ?? [];
+    if (declaredClaims.length > 0) {
+      const missingClaim = declaredClaims.find((claim) => {
+        const surface = observedById.get(claim.surfaceId);
+        return !surface || !(surface.skillCount >= 1);
+      });
+      if (!missingClaim) continue;
+      const surface = observedById.get(missingClaim.surfaceId);
+      missing.push({ host: expectedHost, skillCount: surface?.skillCount ?? 0 });
+      continue;
+    }
     const surface = (surfaces ?? []).find((item) => item.host === expectedHost);
     if (!surface || !(surface.skillCount >= 1)) {
       missing.push({ host: expectedHost, skillCount: surface?.skillCount ?? 0 });

package/src/core/surface-host-bindings.mjs

@@ -186,3 +186,38 @@ export async function deriveSurfaceHostBinding({ manifest, pluginRoot, platform,
   const host = await normalizeHostId(platform.buildAdapter.name);
   return { surfaceId, host };
 }
+
+/**
+ * Group manifest-backed claims before invoking the closure checker.
+ *
+ * A shared canonical source surface is scanned once. Claims remain complete
+ * for host coverage, while checker overrides are passed only for an
+ * unshared surface; this keeps the checker fail-closed when called directly
+ * with conflicting host claims.
+ *
+ * @param {Array<{surfaceId: string, host: string}>} claims
+ * @returns {{ coverageClaims: Array<{surfaceId: string, host: string}>, checkerBindings: Array<{surfaceId: string, host: string}> }}
+ */
+export function groupSurfaceHostBindings(claims = []) {
+  if (!Array.isArray(claims)) {
+    throw new TypeError('surfaceHostBindings must be an array');
+  }
+  const bySurface = new Map();
+  for (const claim of claims) {
+    if (!claim || typeof claim !== 'object'
+        || typeof claim.surfaceId !== 'string' || typeof claim.host !== 'string') {
+      throw new TypeError('surfaceHostBindings entries must be objects with string surfaceId and host');
+    }
+    const existing = bySurface.get(claim.surfaceId) ?? [];
+    existing.push({ surfaceId: claim.surfaceId, host: claim.host });
+    bySurface.set(claim.surfaceId, existing);
+  }
+  const coverageClaims = [...bySurface.values()]
+    .flat()
+    .sort((left, right) => left.surfaceId.localeCompare(right.surfaceId) || left.host.localeCompare(right.host));
+  const checkerBindings = [...bySurface.values()]
+    .filter((surfaceClaims) => surfaceClaims.length === 1)
+    .map(([claim]) => claim)
+    .sort((left, right) => left.surfaceId.localeCompare(right.surfaceId) || left.host.localeCompare(right.host));
+  return { coverageClaims, checkerBindings };
+}