@postman-cse/onboarding-bootstrap 2.9.4 → 2.9.5

package/dist/action.cjs

@@ -99989,11 +99989,11 @@ var require_valid = __commonJS({
 var require_clean = __commonJS({
   "node_modules/postman-collection/node_modules/semver/functions/clean.js"(exports2, module2) {
     var parse10 = require_parse6();
-    var clean = (version, options) => {
+    var clean2 = (version, options) => {
       const s = parse10(version.trim().replace(/^[=v]+/, ""), options);
       return s ? s.version : null;
     };
-    module2.exports = clean;
+    module2.exports = clean2;
   }
 });
 
@@ -101304,7 +101304,7 @@ var require_semver2 = __commonJS({
     var identifiers = require_identifiers();
     var parse10 = require_parse6();
     var valid = require_valid();
-    var clean = require_clean();
+    var clean2 = require_clean();
     var inc = require_inc();
     var diff = require_diff();
     var major = require_major();
@@ -101342,7 +101342,7 @@ var require_semver2 = __commonJS({
     module2.exports = {
       parse: parse10,
       valid,
-      clean,
+      clean: clean2,
       inc,
       diff,
       major,
@@ -256197,8 +256197,8 @@ function getIDToken(aud) {
 }
 
 // src/index.ts
-var import_node_crypto5 = require("node:crypto");
-var import_node_fs5 = require("node:fs");
+var import_node_crypto6 = require("node:crypto");
+var import_node_fs6 = require("node:fs");
 var path9 = __toESM(require("node:path"), 1);
 var import_yaml4 = __toESM(require_dist(), 1);
 
@@ -256306,6 +256306,12 @@ var bootstrapActionContract = {
       default: "",
       allowedValues: ["3.0", "3.1"]
     },
+    "preserve-oas30-type-null": {
+      description: "Opt-in compatibility mode for legacy OpenAPI 3.0 oneOf schemas that pair a normal schema with type: null. The original source bytes are uploaded unchanged while an internal nullable view is used for validation and generated artifacts.",
+      required: false,
+      default: "false",
+      allowedValues: ["true", "false"]
+    },
     "breaking-change-mode": {
       description: "OpenAPI breaking-change comparison mode.",
       required: false,
@@ -256362,6 +256368,20 @@ var bootstrapActionContract = {
       default: "warn",
       allowedValues: ["enforce", "warn"]
     },
+    "branch-strategy": {
+      description: "Branch-aware sync strategy. legacy (default) keeps branch-blind behavior; publish-gate restricts canonical writes to the canonical branch and runs credential-free static validation on other branches; preview additionally maintains suffixed per-branch preview asset sets.",
+      required: false,
+      default: "legacy",
+      allowedValues: ["legacy", "preview", "publish-gate"]
+    },
+    "canonical-branch": {
+      description: "Explicit canonical branch (the sole writer of canonical assets). Defaults to the provider-resolved default branch; required on providers without a default-branch variable (Bitbucket, Azure DevOps) when branch-strategy is not legacy.",
+      required: false
+    },
+    "channels": {
+      description: 'Comma-separated channel map for long-lived promotion branches, e.g. "develop=DEV, staging=STAGE, release/*=RC". Channel branches maintain prefix-named parallel asset sets and never mutate canonical assets.',
+      required: false
+    },
     "integration-backend": {
       description: "Integration backend for downstream workspace connectivity.",
       required: false,
@@ -256431,6 +256451,21 @@ var bootstrapActionContract = {
     },
     "breaking-change-summary-json": {
       description: "JSON summary of the OpenAPI breaking-change check."
+    },
+    "sync-status": {
+      description: "Branch-aware sync status: synced (canonical/channel/preview write ran), skipped-branch-gate (gated run, credential-free validation only), or empty under branch-strategy legacy."
+    },
+    "branch-decision": {
+      description: "Serialized BranchDecision JSON for downstream actions (also exported as POSTMAN_BRANCH_DECISION)."
+    },
+    "spec-version-tag": {
+      description: "Native Spec Hub version tag applied on this canonical publish (tag-per-publish), empty when tagging was skipped (no-op sync, non-canonical run, or legacy client)."
+    },
+    "spec-version-url": {
+      description: "Reserved for the repo-sync finalizer; bootstrap does not tag before complete onboarding."
+    },
+    "spec-content-changed": {
+      description: "Whether bootstrap changed canonical spec content; repo-sync uses this to skip native version tags on no-op syncs."
     }
   },
   retainedBehavior: [
@@ -257557,6 +257592,15 @@ function assertSupportedLocalViewContract(node, options) {
 }
 
 // src/lib/postman/additional-collections.ts
+var RESOURCES_STATE_VERSION = 2;
+var SUPPORTED_STATE_VERSIONS = /* @__PURE__ */ new Set([1, RESOURCES_STATE_VERSION]);
+var StateUnreadableError = class extends Error {
+  code = "CONTRACT_STATE_UNREADABLE";
+  constructor(message) {
+    super(`CONTRACT_STATE_UNREADABLE: ${message}`);
+    this.name = "StateUnreadableError";
+  }
+};
 var ADDITIONAL_COLLECTION_EXTENSIONS = /* @__PURE__ */ new Set([".json", ".yaml", ".yml"]);
 var POSTMAN_COLLECTION_V21_SCHEMA_FRAGMENT = "/collection/v2.1.0/collection.json";
 var V3_DEFINITION_PATH = import_node_path2.default.join(".resources", "definition.yaml");
@@ -257612,16 +257656,46 @@ function resourcesStatePath() {
   return import_node_path2.default.join(workspaceRootForLocalInputs(), RESOURCES_PATH);
 }
 function readResourcesState() {
+  let raw;
   try {
-    return (0, import_yaml.parse)((0, import_node_fs2.readFileSync)(resourcesStatePath(), "utf8"));
+    raw = (0, import_node_fs2.readFileSync)(resourcesStatePath(), "utf8");
   } catch {
     return null;
   }
+  let parsed;
+  try {
+    parsed = (0, import_yaml.parse)(raw);
+  } catch (error2) {
+    throw new StateUnreadableError(
+      `.postman/resources.yaml exists but is not parseable YAML (${error2 instanceof Error ? error2.message : String(error2)}). Fix or delete the file; refusing to treat tracked state as absent.`
+    );
+  }
+  if (parsed === null || parsed === void 0) {
+    return null;
+  }
+  if (typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new StateUnreadableError(
+      ".postman/resources.yaml exists but does not contain a YAML mapping. Fix or delete the file; refusing to treat tracked state as absent."
+    );
+  }
+  const state = parsed;
+  if (state.version !== void 0 && !SUPPORTED_STATE_VERSIONS.has(Number(state.version))) {
+    throw new StateUnreadableError(
+      `.postman/resources.yaml declares unsupported state version ${String(state.version)} (supported: 1, ${RESOURCES_STATE_VERSION}). Upgrade the action or fix the file.`
+    );
+  }
+  if (state.canonical && !state.cloudResources) {
+    state.cloudResources = { ...state.canonical };
+  }
+  return state;
 }
 function writeResourcesState(state) {
   const target = resourcesStatePath();
   (0, import_node_fs2.mkdirSync)(import_node_path2.default.dirname(target), { recursive: true });
-  (0, import_node_fs2.writeFileSync)(target, (0, import_yaml.stringify)(state), "utf8");
+  const canonical = state.cloudResources ?? state.canonical ?? {};
+  const persisted = { ...state, version: RESOURCES_STATE_VERSION, canonical };
+  delete persisted.cloudResources;
+  (0, import_node_fs2.writeFileSync)(target, (0, import_yaml.stringify)(persisted), "utf8");
 }
 function findCloudResourceId(map, matcher) {
   if (!map) {
@@ -257631,7 +257705,7 @@ function findCloudResourceId(map, matcher) {
   return match?.[1];
 }
 function findExistingAdditionalCollectionId(resourcesState, resourcePath) {
-  return resourcesState?.cloudResources?.additionalCollections?.[resourcePath] ?? resourcesState?.cloudResources?.collections?.[resourcePath];
+  return resourcesState?.canonical?.additionalCollections?.[resourcePath] ?? resourcesState?.canonical?.collections?.[resourcePath] ?? resourcesState?.cloudResources?.additionalCollections?.[resourcePath] ?? resourcesState?.cloudResources?.collections?.[resourcePath];
 }
 function resolveAdditionalCollectionsDir(directoryInput) {
   const workspaceRoot = workspaceRootForLocalInputs();
@@ -258633,6 +258707,8 @@ var BifrostInternalIntegrationAdapter = class _BifrostInternalIntegrationAdapter
    * endpoint aborts rather than blocking the run forever. */
   static REQUEST_TIMEOUT_MS = 3e4;
   static POSTMAN_APP_VERSION_URL = `https://dl.pstmn.io/update/status?currentVersion=${_BifrostInternalIntegrationAdapter.MINIMUM_POSTMAN_APP_VERSION}&platform=osx_arm64`;
+  /** Concurrent dual-trigger previews share one spec; peer sync holds a 423 lock. */
+  static SYNC_LOCKED_MAX_RETRIES = 6;
   accessToken;
   tokenProvider;
   appVersionPromise;
@@ -258641,6 +258717,7 @@ var BifrostInternalIntegrationAdapter = class _BifrostInternalIntegrationAdapter
   gatewayBaseUrl;
   orgMode;
   secretMasker;
+  sleep;
   teamId;
   constructor(options) {
     this.accessToken = String(options.accessToken || "").trim();
@@ -258654,6 +258731,7 @@ var BifrostInternalIntegrationAdapter = class _BifrostInternalIntegrationAdapter
     ).replace(/\/+$/, "");
     this.orgMode = options.orgMode ?? false;
     this.secretMasker = options.secretMasker ?? createSecretMasker([this.accessToken]);
+    this.sleep = options.sleep ?? ((delayMs) => new Promise((resolve5) => setTimeout(resolve5, delayMs)));
     this.teamId = String(options.teamId || "").trim();
   }
   configureTeamContext(teamId, orgMode) {
@@ -258860,55 +258938,72 @@ var BifrostInternalIntegrationAdapter = class _BifrostInternalIntegrationAdapter
     if (collections.length === 0) {
       return;
     }
-    const response = await this.proxyRequest(
-      "specification",
-      "put",
-      `/specifications/${specificationId}/collections`,
-      collections.map((collection) => ({
-        collectionId: collection.collectionId,
-        ...collection.syncOptions ? { syncOptions: collection.syncOptions } : {}
-      }))
-    );
-    if (response.ok) {
-      return;
+    const body2 = collections.map((collection) => ({
+      collectionId: collection.collectionId,
+      ...collection.syncOptions ? { syncOptions: collection.syncOptions } : {}
+    }));
+    for (let lockedAttempt = 0; ; lockedAttempt += 1) {
+      const response = await this.proxyRequest(
+        "specification",
+        "put",
+        `/specifications/${specificationId}/collections`,
+        body2
+      );
+      if (response.ok) {
+        return;
+      }
+      const httpErr = await HttpError.fromResponse(response, {
+        method: "POST",
+        requestHeaders: {
+          "Content-Type": "application/json",
+          "x-access-token": this.currentToken(),
+          ...this.teamId && this.orgMode ? { "x-entity-team-id": this.teamId } : {}
+        },
+        secretValues: [this.currentToken()],
+        url: `${this.bifrostBaseUrl}/ws/proxy`
+      });
+      if (httpErr.status === 423 && lockedAttempt < _BifrostInternalIntegrationAdapter.SYNC_LOCKED_MAX_RETRIES) {
+        await this.sleep(2e3 * Math.pow(2, lockedAttempt));
+        continue;
+      }
+      const advised = adviseFromHttpError(
+        httpErr,
+        this.adviceContext("collection-to-specification linking")
+      );
+      throw advised ?? httpErr;
     }
-    const httpErr = await HttpError.fromResponse(response, {
-      method: "POST",
-      requestHeaders: {
-        "Content-Type": "application/json",
-        "x-access-token": this.currentToken(),
-        ...this.teamId && this.orgMode ? { "x-entity-team-id": this.teamId } : {}
-      },
-      secretValues: [this.currentToken()],
-      url: `${this.bifrostBaseUrl}/ws/proxy`
-    });
-    const advised = adviseFromHttpError(
-      httpErr,
-      this.adviceContext("collection-to-specification linking")
-    );
-    throw advised ?? httpErr;
   }
   async syncCollection(specificationId, collectionId) {
-    const response = await this.proxyRequest(
-      "specification",
-      "post",
-      `/specifications/${specificationId}/collections/${collectionId}/sync`
-    );
-    if (response.ok) {
-      return;
+    for (let lockedAttempt = 0; ; lockedAttempt += 1) {
+      const response = await this.proxyRequest(
+        "specification",
+        "post",
+        `/specifications/${specificationId}/collections/${collectionId}/sync`
+      );
+      if (response.ok) {
+        return;
+      }
+      const bodyText = await response.clone().text().catch(() => "");
+      if (response.status === 400 && /already in sync/i.test(bodyText)) {
+        return;
+      }
+      const httpErr = await HttpError.fromResponse(response, {
+        method: "POST",
+        requestHeaders: {
+          "Content-Type": "application/json",
+          "x-access-token": this.currentToken(),
+          ...this.teamId && this.orgMode ? { "x-entity-team-id": this.teamId } : {}
+        },
+        secretValues: [this.currentToken()],
+        url: `${this.bifrostBaseUrl}/ws/proxy`
+      });
+      if (httpErr.status === 423 && lockedAttempt < _BifrostInternalIntegrationAdapter.SYNC_LOCKED_MAX_RETRIES) {
+        await this.sleep(2e3 * Math.pow(2, lockedAttempt));
+        continue;
+      }
+      const advised = adviseFromHttpError(httpErr, this.adviceContext("collection sync"));
+      throw advised ?? httpErr;
     }
-    const httpErr = await HttpError.fromResponse(response, {
-      method: "POST",
-      requestHeaders: {
-        "Content-Type": "application/json",
-        "x-access-token": this.currentToken(),
-        ...this.teamId && this.orgMode ? { "x-entity-team-id": this.teamId } : {}
-      },
-      secretValues: [this.currentToken()],
-      url: `${this.bifrostBaseUrl}/ws/proxy`
-    });
-    const advised = adviseFromHttpError(httpErr, this.adviceContext("collection sync"));
-    throw advised ?? httpErr;
   }
   async getWorkspaceGitRepoUrl(workspaceId) {
     const response = await this.proxyRequest(
@@ -264053,6 +264148,16 @@ var PostmanGatewayAssetsClient = class _PostmanGatewayAssetsClient {
     if (openapiVersion !== "3.0" && openapiVersion !== "3.1") {
       throw new Error(`uploadSpec: unsupported openapiVersion "${openapiVersion}". Expected '3.0' or '3.1'.`);
     }
+    const before = await this.findSpecificationsByExactName(workspaceId, projectName);
+    const existing = adoptExactMatch(
+      `specification:${workspaceId}:${projectName}`,
+      before,
+      (entry) => entry.id
+    );
+    if (existing) {
+      await this.updateSpec(existing.id, specContent, workspaceId);
+      return existing.id;
+    }
     const specType = openapiVersion === "3.1" ? "OPENAPI:3.1" : "OPENAPI:3.0";
     let created;
     try {
@@ -264077,10 +264182,49 @@ var PostmanGatewayAssetsClient = class _PostmanGatewayAssetsClient {
       if (!match) throw error2;
       created = { data: { id: match.id } };
     }
-    const specId = String(asRecord8(created?.data)?.id ?? created?.id ?? "").trim();
+    let specId = String(asRecord8(created?.data)?.id ?? created?.id ?? "").trim();
     if (!specId) {
       throw new Error("Spec upload did not return an ID");
     }
+    let matches = await this.findSpecificationsByExactName(workspaceId, projectName);
+    if (before.length === 0 && matches.length <= 1) {
+      await this.sleep(1e3);
+      const settled = await this.findSpecificationsByExactName(workspaceId, projectName);
+      if (settled.length > 0) matches = settled;
+    }
+    if (matches.length > 1 && before.length === 0) {
+      for (const duplicate of matches.slice(1)) {
+        try {
+          await this.deleteSpecification(duplicate.id);
+        } catch (error2) {
+          if (!(error2 instanceof HttpError && error2.status === 404)) throw error2;
+        }
+      }
+      for (let attempt = 0; attempt < 5; attempt += 1) {
+        matches = await this.findSpecificationsByExactName(workspaceId, projectName);
+        if (matches.length <= 1) break;
+        await this.sleep(250 * (attempt + 1));
+      }
+      const converged = adoptExactMatch(
+        `specification:${workspaceId}:${projectName}`,
+        matches,
+        (entry) => entry.id
+      );
+      if (!converged) {
+        throw new Error(`Concurrent specification create for ${projectName} did not converge`);
+      }
+      specId = converged.id;
+      if (specId !== String(asRecord8(created?.data)?.id ?? created?.id ?? "").trim()) {
+        await this.updateSpec(specId, specContent, workspaceId);
+      }
+    } else {
+      const verified = adoptExactMatch(
+        `specification:${workspaceId}:${projectName}`,
+        matches,
+        (entry) => entry.id
+      );
+      if (verified) specId = verified.id;
+    }
     await this.gateway.requestJson({
       service: "specification",
       method: "get",
@@ -264088,6 +264232,14 @@ var PostmanGatewayAssetsClient = class _PostmanGatewayAssetsClient {
     });
     return specId;
   }
+  async deleteSpecification(specId) {
+    await this.gateway.requestJson({
+      service: "specification",
+      method: "delete",
+      path: `/specifications/${specId}`,
+      retry: "none"
+    });
+  }
   async findSpecificationsByExactName(workspaceId, name) {
     const response = await this.gateway.requestJson({
       service: "specification",
@@ -264151,6 +264303,41 @@ var PostmanGatewayAssetsClient = class _PostmanGatewayAssetsClient {
       return void 0;
     }
   }
+  /**
+   * Native Spec Hub version tags (branch-aware sync P3.5). Tags attach to the
+   * LATEST changelog group; the backend 409s when that group is already tagged
+   * (VersionControlService). Callers handle 409 as idempotent-by-group.
+   */
+  async tagSpecVersion(specId, name) {
+    const trimmed = name.trim().slice(0, 255);
+    const created = await this.gateway.requestJson({
+      service: "specification",
+      method: "post",
+      path: `/specifications/${specId}/tags`,
+      retry: "none",
+      body: { name: trimmed }
+    });
+    const record = asRecord8(created?.data) ?? created ?? {};
+    return {
+      id: String(record.id ?? "").trim(),
+      name: String(record.name ?? trimmed).trim()
+    };
+  }
+  /** List a spec's native version tags (newest first per backend ordering). */
+  async listSpecVersionTags(specId) {
+    const response = await this.gateway.requestJson({
+      service: "specification",
+      method: "get",
+      path: `/specifications/${specId}/tags`,
+      query: { limit: "50" }
+    });
+    const entries = Array.isArray(response?.data) ? response.data : [];
+    return entries.map((value) => asRecord8(value)).filter((value) => value !== null).map((value) => ({
+      id: String(value.id ?? "").trim(),
+      // listTags returns `message`; createTag returns `name`. Accept both.
+      name: String(value.name ?? value.message ?? "").trim()
+    })).filter((value) => value.id || value.name);
+  }
   /** Resolve a specification's ROOT file uuid via the files list. */
   async resolveRootFileId(specId) {
     const files = await this.gateway.requestJson({
@@ -264170,79 +264357,182 @@ var PostmanGatewayAssetsClient = class _PostmanGatewayAssetsClient {
    */
   async generateCollection(specId, projectName, prefix, folderStrategy, nestedFolderHierarchy, requestNameSource) {
     const name = [prefix.trim(), projectName.trim()].filter(Boolean).join(" ");
-    const submittedName = `${name} [bootstrap:${this.createIdentity()}]`;
-    const body2 = {
-      name: submittedName,
-      options: {
-        requestNameSource,
-        folderStrategy,
-        ...folderStrategy === "Tags" ? { nestedFolderHierarchy } : {}
-      }
-    };
     const before = await this.listGeneratedCollectionRefs(specId);
-    let taskId;
-    try {
-      taskId = await this.postGenerationWithLockRetry(specId, body2);
-    } catch (error2) {
-      if (!isAmbiguousTransportError(error2)) throw error2;
-      const beforeIds2 = new Set(before.map((entry) => entry.id));
-      const appeared2 = (await this.listGeneratedCollectionRefs(specId)).filter(
-        (entry) => !beforeIds2.has(entry.id)
-      );
-      const exactAppeared = await this.filterGeneratedCollectionsByExactName(
-        appeared2,
+    const existing = adoptExactMatch(
+      `generated-collection:${specId}:${name}`,
+      await this.filterGeneratedCollectionsByExactName(before, name),
+      (entry) => entry.id
+    );
+    if (existing) return this.convergeGeneratedCollections(specId, name, existing.id);
+    let lastError;
+    for (let taskAttempt = 0; taskAttempt < 2; taskAttempt += 1) {
+      const submittedName = `${name} [bootstrap:${this.createIdentity()}]`;
+      const body2 = {
+        name: submittedName,
+        options: {
+          requestNameSource,
+          folderStrategy,
+          ...folderStrategy === "Tags" ? { nestedFolderHierarchy } : {}
+        }
+      };
+      let taskId;
+      try {
+        const generation = await this.postGenerationWithLockRetry(specId, body2, name);
+        if (generation.adoptedId) {
+          return this.convergeGeneratedCollections(specId, name, generation.adoptedId);
+        }
+        taskId = generation.taskId ?? "";
+      } catch (error2) {
+        if (!isAmbiguousTransportError(error2)) throw error2;
+        const beforeIds2 = new Set(before.map((entry) => entry.id));
+        const appeared2 = (await this.listGeneratedCollectionRefs(specId)).filter(
+          (entry) => !beforeIds2.has(entry.id)
+        );
+        const exactAppeared = await this.filterGeneratedCollectionsByExactName(
+          appeared2,
+          submittedName
+        );
+        const match = adoptExactMatch(
+          `generated-collection:${specId}:${submittedName}`,
+          exactAppeared,
+          (entry) => entry.id
+        );
+        if (!match) throw error2;
+        await this.renameGeneratedCollection(match.id, name);
+        return this.convergeGeneratedCollections(specId, name, match.id);
+      }
+      let taskFailed = false;
+      if (taskId) {
+        for (let attempt = 0; attempt < this.generationPollAttempts; attempt += 1) {
+          await this.sleep(this.generationPollDelayMs);
+          const task = await this.gateway.requestJson({
+            service: "specification",
+            method: "get",
+            path: "/tasks",
+            query: { entityId: specId, entityType: "specification", type: "collection-generation" }
+          });
+          const status = String(asRecord8(task?.data)?.[taskId] ?? "").toLowerCase();
+          if (status === "failed" || status === "error") {
+            taskFailed = true;
+            lastError = new Error(`Collection generation task failed for ${prefix}`);
+            break;
+          }
+          if (status && status !== "in-progress" && status !== "pending" && status !== "queued") {
+            break;
+          }
+          if (attempt === this.generationPollAttempts - 1) {
+            throw new Error(`Collection generation timed out for ${prefix}`);
+          }
+        }
+      }
+      if (taskFailed) {
+        await this.sleep(1e3 * (taskAttempt + 1));
+        continue;
+      }
+      const beforeIds = new Set(before.map((entry) => entry.id));
+      const after = await this.listGeneratedCollectionRefs(specId);
+      const appeared = after.filter((entry) => !beforeIds.has(entry.id));
+      const candidates = await this.filterGeneratedCollectionsByExactName(
+        appeared,
         submittedName
       );
-      const match = adoptExactMatch(
+      const uid = adoptExactMatch(
         `generated-collection:${specId}:${submittedName}`,
-        exactAppeared,
+        candidates,
         (entry) => entry.id
-      );
-      if (!match) throw error2;
-      await this.renameGeneratedCollection(match.id, name);
-      return match.id;
+      )?.id;
+      if (!uid) {
+        throw new Error(`Collection generation did not yield a collection uid for ${prefix}`);
+      }
+      await this.renameGeneratedCollection(uid, name);
+      return this.convergeGeneratedCollections(specId, name, uid);
     }
-    if (taskId) {
-      for (let attempt = 0; attempt < this.generationPollAttempts; attempt += 1) {
-        await this.sleep(this.generationPollDelayMs);
-        const task = await this.gateway.requestJson({
-          service: "specification",
-          method: "get",
-          path: "/tasks",
-          query: { entityId: specId, entityType: "specification", type: "collection-generation" }
-        });
-        const status = String(asRecord8(task?.data)?.[taskId] ?? "").toLowerCase();
-        if (status === "failed" || status === "error") {
-          throw new Error(`Collection generation task failed for ${prefix}`);
-        }
-        if (status && status !== "in-progress" && status !== "pending" && status !== "queued") {
-          break;
-        }
-        if (attempt === this.generationPollAttempts - 1) {
-          throw new Error(`Collection generation timed out for ${prefix}`);
+    throw lastError ?? new Error(`Collection generation task failed for ${prefix}`);
+  }
+  /**
+   * Re-elect the durable generated collection for a final name. Call after
+   * concurrent dual-trigger generates and before description/inject/tag so a
+   * peer orphan-sweep cannot leave this runner holding a deleted id.
+   */
+  async adoptGeneratedCollection(specId, projectName, prefix, preferredId = "") {
+    const name = [prefix.trim(), projectName.trim()].filter(Boolean).join(" ");
+    return this.convergeGeneratedCollections(specId, name, preferredId);
+  }
+  /**
+   * Concurrent dual-trigger previews can each generate+rename the same final
+   * collection identity. Elect the stable lowest-id winner.
+   *
+   * Losers only delete *their own* preferred collection (never a peer's still-
+   * in-use id). Winners wait briefly for peers to self-delete, then clean any
+   * leftover same-identity orphans (temps + extra finals).
+   */
+  async convergeGeneratedCollections(specId, finalName, preferredId) {
+    const tempPrefix = `${finalName} [bootstrap:`;
+    const hydrate = async () => {
+      const linked = await this.listGeneratedCollectionRefs(specId);
+      return Promise.all(
+        linked.map(async (entry) => {
+          if (entry.name) return { id: entry.id, name: entry.name };
+          try {
+            const collection = await this.gateway.requestJson({
+              service: "collection",
+              method: "get",
+              path: `/v3/collections/${this.bareModelId(entry.id)}`
+            });
+            return {
+              id: entry.id,
+              name: String(asRecord8(collection?.data)?.name ?? "").trim()
+            };
+          } catch (error2) {
+            if (error2 instanceof HttpError && error2.status === 404) {
+              return { id: entry.id, name: "" };
+            }
+            throw error2;
+          }
+        })
+      );
+    };
+    const selectSameIdentity = (entries) => entries.filter(
+      (entry) => entry.name === finalName || entry.name.startsWith(tempPrefix)
+    ).sort((a, b) => a.id.localeCompare(b.id));
+    let sameIdentity = selectSameIdentity(await hydrate());
+    if (sameIdentity.length === 0) return preferredId;
+    if (sameIdentity.length === 1) {
+      await this.sleep(1e3);
+      sameIdentity = selectSameIdentity(await hydrate());
+      if (sameIdentity.length === 0) return preferredId;
+    }
+    const winner = sameIdentity[0];
+    if (winner.name !== finalName) {
+      await this.renameGeneratedCollection(winner.id, finalName);
+    }
+    if (preferredId && preferredId !== winner.id) {
+      const own = sameIdentity.find((entry) => entry.id === preferredId);
+      if (own) {
+        try {
+          await this.deleteCollection(preferredId);
+        } catch (error2) {
+          if (!(error2 instanceof HttpError && error2.status === 404)) throw error2;
         }
       }
+      return winner.id;
     }
-    const beforeIds = new Set(before.map((entry) => entry.id));
-    const after = await this.listGeneratedCollectionRefs(specId);
-    const appeared = after.filter((entry) => !beforeIds.has(entry.id));
-    const candidates = await this.filterGeneratedCollectionsByExactName(
-      appeared,
-      submittedName
-    );
-    const uid = adoptExactMatch(
-      `generated-collection:${specId}:${submittedName}`,
-      candidates,
-      (entry) => entry.id
-    )?.id;
-    if (!uid) {
-      throw new Error(`Collection generation did not yield a collection uid for ${prefix}`);
+    if (sameIdentity.length > 1) {
+      await this.sleep(1500);
+      sameIdentity = selectSameIdentity(await hydrate());
+      for (const duplicate of sameIdentity) {
+        if (duplicate.id === winner.id) continue;
+        try {
+          await this.deleteCollection(duplicate.id);
+        } catch (error2) {
+          if (!(error2 instanceof HttpError && error2.status === 404)) throw error2;
+        }
+      }
     }
-    await this.renameGeneratedCollection(uid, name);
-    return uid;
+    return winner.id;
   }
   /** POST the generation request, retrying a 423-locked spec; returns the task id. */
-  async postGenerationWithLockRetry(specId, body2) {
+  async postGenerationWithLockRetry(specId, body2, finalName) {
     for (let lockedAttempt = 0; ; lockedAttempt += 1) {
       try {
         const created = await this.gateway.requestJson({
@@ -264252,13 +264542,22 @@ var PostmanGatewayAssetsClient = class _PostmanGatewayAssetsClient {
           retry: "none",
           body: body2
         });
-        return String(asRecord8(created?.data)?.taskId ?? "").trim();
+        return { taskId: String(asRecord8(created?.data)?.taskId ?? "").trim() };
       } catch (error2) {
         const locked = error2 instanceof HttpError && error2.status === 423;
         if (!locked || lockedAttempt >= _PostmanGatewayAssetsClient.GENERATION_LOCKED_MAX_RETRIES) {
           throw error2;
         }
         await this.sleep(5e3 * Math.pow(2, lockedAttempt));
+        const adopted = adoptExactMatch(
+          `generated-collection:${specId}:${finalName}`,
+          await this.filterGeneratedCollectionsByExactName(
+            await this.listGeneratedCollectionRefs(specId),
+            finalName
+          ),
+          (entry) => entry.id
+        );
+        if (adopted) return { adoptedId: adopted.id };
       }
     }
   }
@@ -264295,14 +264594,24 @@ var PostmanGatewayAssetsClient = class _PostmanGatewayAssetsClient {
     return hydrated.filter((entry) => entry.name === expectedName);
   }
   async renameGeneratedCollection(collectionId, name) {
-    await this.gateway.requestJson({
-      service: "collection",
-      method: "patch",
-      path: `/v3/collections/${this.bareModelId(collectionId)}`,
-      // Replacing a generated collection's name with the same value is idempotent.
-      retry: "safe",
-      body: [{ op: "replace", path: "/name", value: name }]
-    });
+    try {
+      await this.gateway.requestJson({
+        service: "collection",
+        method: "patch",
+        path: `/v3/collections/${this.bareModelId(collectionId)}`,
+        // Replacing a generated collection's name with the same value is idempotent.
+        retry: "safe",
+        body: [{ op: "replace", path: "/name", value: name }]
+      });
+    } catch (error2) {
+      if (error2 instanceof HttpError && error2.status === 400 && /must update at least one|REJECTED_PATCH/i.test(
+        `${error2.message}
+${error2.responseBody ?? ""}`
+      )) {
+        return;
+      }
+      throw error2;
+    }
   }
   /**
    * Create a team-visible workspace through the gateway workspaces service.
@@ -264577,6 +264886,7 @@ var PostmanGatewayAssetsClient = class _PostmanGatewayAssetsClient {
       service: "tagging",
       method: "put",
       path: `/v1/tags/collections/${collectionUid}`,
+      retry: "safe",
       body: { tags: normalized.map((slug) => ({ slug })) }
     });
   }
@@ -265203,6 +265513,15 @@ var PostmanGatewayAssetsClient = class _PostmanGatewayAssetsClient {
   async createCollection(workspaceId, collection, options = {}) {
     const v3 = this.normalizeCollectionForWrite(collection);
     const desiredName = String(v3.name ?? "Untitled Collection");
+    const existing = adoptExactMatch(
+      `collection:${workspaceId}:${desiredName}`,
+      await this.findCollectionsByExactName(workspaceId, desiredName),
+      (entry) => entry.id
+    );
+    if (existing) {
+      await this.updateCollection(existing.id, collection);
+      return existing.id;
+    }
     const submittedName = `${desiredName} [bootstrap:${this.createIdentity()}]`;
     const rootBody = { name: submittedName };
     let created;
@@ -265253,6 +265572,10 @@ var PostmanGatewayAssetsClient = class _PostmanGatewayAssetsClient {
     }
     return rawId;
   }
+  /** Patch only the durable collection description without reconciling its item tree. */
+  async updateCollectionDescription(collectionUid, description) {
+    await this.applyCollectionLevelSettings(this.bareModelId(collectionUid), { description });
+  }
   /**
    * Full-replace reconcile of a curated local v2.1.0 or collection v3 payload: delete every
    * root-level item (deleting a folder cascades its children server-side —
@@ -265477,7 +265800,8 @@ var AccessTokenGatewayClient = class {
    * `requestJson` can still parse it.
    */
   rebuildResponse(response, body2) {
-    return new Response(body2, {
+    const nullBody = response.status === 204 || response.status === 205 || response.status === 304;
+    return new Response(nullBody ? null : body2, {
       status: response.status,
       statusText: response.statusText,
       headers: response.headers
@@ -281929,6 +282253,61 @@ function serializeOpenApiDocument(document2) {
   return `${JSON.stringify(document2, null, 2)}
 `;
 }
+function typeNullPath(pathSegments) {
+  return pathSegments.map(String).join(".");
+}
+function isNullOnlySchema(value) {
+  const record = asRecord10(value);
+  if (!record || record.type !== "null") return false;
+  return Object.keys(record).every((key) => key === "type" || key.startsWith("x-"));
+}
+function createOas30TypeNullCompatibilityDocument(sourceDocument) {
+  const document2 = structuredClone(sourceDocument);
+  const sourceTypeNullPaths = [];
+  const visit4 = (value, pathSegments) => {
+    if (Array.isArray(value)) {
+      value.forEach((entry, index) => visit4(entry, [...pathSegments, index]));
+      return;
+    }
+    const record = asRecord10(value);
+    if (!record) return;
+    const oneOf = Array.isArray(record.oneOf) ? record.oneOf : void 0;
+    const nullIndexes = oneOf ? oneOf.flatMap((entry, index) => isNullOnlySchema(entry) ? [index] : []) : [];
+    if (nullIndexes.length > 0) {
+      if (oneOf?.length !== 2 || nullIndexes.length !== 1) {
+        throw new Error(
+          `CONTRACT_OAS30_TYPE_NULL_UNSUPPORTED: ${typeNullPath(pathSegments)} must use oneOf with exactly one null-only member and one non-null schema`
+        );
+      }
+      const nullIndex = nullIndexes[0];
+      const nonNullIndex = nullIndex === 0 ? 1 : 0;
+      const nonNullSchema = asRecord10(oneOf[nonNullIndex]);
+      if (!nonNullSchema || nonNullSchema.type === "null") {
+        throw new Error(
+          `CONTRACT_OAS30_TYPE_NULL_UNSUPPORTED: ${typeNullPath(pathSegments)} must pair the null-only member with one non-null schema`
+        );
+      }
+      const siblings = Object.fromEntries(
+        Object.entries(record).filter(([key]) => key !== "oneOf")
+      );
+      for (const key of Object.keys(record)) delete record[key];
+      Object.assign(record, structuredClone(nonNullSchema), siblings, { nullable: true });
+      sourceTypeNullPaths.push(typeNullPath([...pathSegments, "oneOf", nullIndex, "type"]));
+      visit4(record, pathSegments);
+      return;
+    }
+    if (record.type === "null") {
+      throw new Error(
+        `CONTRACT_OAS30_TYPE_NULL_UNSUPPORTED: ${typeNullPath([...pathSegments, "type"])} is not a supported nullable oneOf member`
+      );
+    }
+    for (const [key, child4] of Object.entries(record)) {
+      visit4(child4, [...pathSegments, key]);
+    }
+  };
+  visit4(document2, []);
+  return { document: document2, sourceTypeNullPaths };
+}
 async function bundleSpec(baseUrl, document2, options) {
   const budget = options.budget ?? { refs: 0, totalBytes: Buffer.byteLength(JSON.stringify(document2), "utf8") };
   const fetchText = options.fetchText ?? safeFetchText;
@@ -281970,7 +282349,14 @@ function createCachedFetchText(options) {
 async function buildLoadedSpec(content, baseRef, options, fetchText, budget) {
   const document2 = parseOpenApiDocument(content);
   const version = detectOpenApiVersion2(document2);
-  const bundledDocument = await bundleSpec(baseRef, document2, { ...options, budget, fetchText });
+  let contractDocument = document2;
+  let sourceTypeNullPaths = [];
+  if (options.preserveOas30TypeNull && version === "3.0") {
+    const compatibility = createOas30TypeNullCompatibilityDocument(document2);
+    contractDocument = compatibility.document;
+    sourceTypeNullPaths = compatibility.sourceTypeNullPaths;
+  }
+  const bundledDocument = await bundleSpec(baseRef, contractDocument, { ...options, budget, fetchText });
   const validation = await validate(bundledDocument, {
     resolve: { external: false, file: false },
     dereference: { circular: "ignore" },
@@ -281984,6 +282370,7 @@ async function buildLoadedSpec(content, baseRef, options, fetchText, budget) {
     bundledDocument,
     contractIndex: buildContractIndex(bundledDocument),
     content,
+    sourceTypeNullPaths,
     version
   };
 }
@@ -282109,6 +282496,309 @@ function looksLikeIntrospection(record) {
   return Boolean(data && typeof data === "object" && data.__schema);
 }
 
+// src/lib/repo/branch-decision.ts
+var import_node_fs5 = require("node:fs");
+var import_node_crypto4 = require("node:crypto");
+var ContractError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(`${code}: ${message}`);
+    this.code = code;
+    this.name = "ContractError";
+  }
+};
+function clean(value) {
+  const trimmed = (value ?? "").trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function stripRefPrefix(ref) {
+  const raw = clean(ref);
+  if (!raw) {
+    return { kind: "unknown" };
+  }
+  if (raw.startsWith("refs/heads/")) {
+    return { name: raw.slice("refs/heads/".length), kind: "branch" };
+  }
+  if (raw.startsWith("refs/tags/")) {
+    return { name: raw.slice("refs/tags/".length), kind: "tag" };
+  }
+  if (raw.startsWith("refs/pull/") || raw.startsWith("refs/merge")) {
+    return { kind: "unknown" };
+  }
+  return { name: raw, kind: "branch" };
+}
+function detectProvider(env) {
+  if (clean(env.GITHUB_ACTIONS) || clean(env.GITHUB_REPOSITORY)) return "github";
+  if (clean(env.GITLAB_CI) || clean(env.CI_PROJECT_PATH)) return "gitlab";
+  if (clean(env.BITBUCKET_REPO_SLUG) || clean(env.BITBUCKET_BRANCH)) return "bitbucket";
+  if (clean(env.TF_BUILD) || clean(env.BUILD_REPOSITORY_URI)) return "azure-devops";
+  return "unknown";
+}
+function readGithubEvent(env) {
+  const path10 = clean(env.GITHUB_EVENT_PATH);
+  if (!path10) return void 0;
+  try {
+    return JSON.parse((0, import_node_fs5.readFileSync)(path10, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function resolveBranchIdentity(env = process.env, overrides = {}) {
+  const provider = detectProvider(env);
+  const explicitDefault = clean(overrides.defaultBranch);
+  let headBranch;
+  let rawRef;
+  let refKind;
+  let isPrContext = false;
+  let isForkPr = false;
+  let defaultBranch = explicitDefault;
+  let headSha;
+  switch (provider) {
+    case "github": {
+      const event2 = readGithubEvent(env);
+      headSha = clean(env.GITHUB_SHA);
+      defaultBranch ??= clean(event2?.repository?.default_branch);
+      const headRef = clean(env.GITHUB_HEAD_REF);
+      if (headRef) {
+        isPrContext = true;
+        headBranch = headRef;
+        rawRef = clean(env.GITHUB_REF) ?? headRef;
+        refKind = "branch";
+        const headRepo = event2?.pull_request?.head?.repo?.full_name;
+        const baseRepo = event2?.pull_request?.base?.repo?.full_name ?? event2?.repository?.full_name;
+        isForkPr = Boolean(headRepo && baseRepo && headRepo !== baseRepo);
+        headSha = clean(event2?.pull_request?.head?.sha) ?? headSha;
+      } else {
+        rawRef = clean(env.GITHUB_REF) ?? clean(env.GITHUB_REF_NAME);
+        const parsed = stripRefPrefix(rawRef);
+        headBranch = parsed.kind === "branch" ? parsed.name : void 0;
+        refKind = parsed.kind;
+      }
+      break;
+    }
+    case "gitlab": {
+      headSha = clean(env.CI_COMMIT_SHA);
+      defaultBranch ??= clean(env.CI_DEFAULT_BRANCH);
+      const mrSource = clean(env.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME);
+      if (mrSource) {
+        isPrContext = true;
+        headBranch = mrSource;
+        rawRef = mrSource;
+        refKind = "branch";
+        const sourceProject = clean(env.CI_MERGE_REQUEST_SOURCE_PROJECT_ID);
+        const targetProject = clean(env.CI_MERGE_REQUEST_PROJECT_ID);
+        isForkPr = Boolean(sourceProject && targetProject && sourceProject !== targetProject);
+      } else if (clean(env.CI_COMMIT_TAG)) {
+        rawRef = clean(env.CI_COMMIT_TAG);
+        refKind = "tag";
+      } else {
+        headBranch = clean(env.CI_COMMIT_BRANCH) ?? clean(env.CI_COMMIT_REF_NAME);
+        rawRef = headBranch;
+        refKind = headBranch ? "branch" : "unknown";
+      }
+      break;
+    }
+    case "bitbucket": {
+      headSha = clean(env.BITBUCKET_COMMIT);
+      if (clean(env.BITBUCKET_TAG)) {
+        rawRef = clean(env.BITBUCKET_TAG);
+        refKind = "tag";
+      } else {
+        headBranch = clean(env.BITBUCKET_BRANCH);
+        rawRef = headBranch;
+        refKind = headBranch ? "branch" : "unknown";
+        isPrContext = Boolean(clean(env.BITBUCKET_PR_ID));
+      }
+      break;
+    }
+    case "azure-devops": {
+      headSha = clean(env.BUILD_SOURCEVERSION);
+      const prSource = clean(env.SYSTEM_PULLREQUEST_SOURCEBRANCH);
+      if (prSource) {
+        isPrContext = true;
+        const parsed = stripRefPrefix(prSource);
+        headBranch = parsed.kind === "branch" ? parsed.name : void 0;
+        rawRef = prSource;
+        refKind = parsed.kind;
+        const forkFlag = clean(env.SYSTEM_PULLREQUEST_ISFORK);
+        isForkPr = forkFlag?.toLowerCase() === "true";
+      } else {
+        rawRef = clean(env.BUILD_SOURCEBRANCH);
+        const parsed = stripRefPrefix(rawRef);
+        headBranch = parsed.kind === "branch" ? parsed.name : void 0;
+        refKind = parsed.kind;
+      }
+      break;
+    }
+    default: {
+      refKind = "unknown";
+    }
+  }
+  if (refKind === "branch" && headBranch && defaultBranch && headBranch === defaultBranch) {
+    refKind = "default-branch";
+  }
+  return { provider, headBranch, rawRef, defaultBranch, refKind, isPrContext, isForkPr, headSha };
+}
+function parseChannelRules(input) {
+  const raw = clean(input);
+  const rules = [];
+  for (const part of raw ? raw.split(",") : []) {
+    const entry = part.trim();
+    if (!entry) continue;
+    const eq = entry.indexOf("=");
+    if (eq <= 0 || eq === entry.length - 1) {
+      throw new ContractError(
+        "CONTRACT_CHANNELS_INPUT_INVALID",
+        `channels entry "${entry}" must be <branch-or-glob>=<CODE>`
+      );
+    }
+    const pattern = entry.slice(0, eq).trim();
+    const code = entry.slice(eq + 1).trim().toUpperCase();
+    if (!/^[A-Z][A-Z0-9_-]{0,15}$/.test(code)) {
+      throw new ContractError(
+        "CONTRACT_CHANNELS_INPUT_INVALID",
+        `channel code "${code}" must be 1-16 chars, A-Z 0-9 _ -, starting with a letter`
+      );
+    }
+    rules.push({ pattern, code });
+  }
+  if (!rules.some((rule) => rule.pattern === "release/*")) {
+    rules.push({ pattern: "release/*", code: "RC" });
+  }
+  return rules;
+}
+function matchChannel(branch, rules) {
+  for (const rule of rules) {
+    if (rule.pattern.endsWith("*")) {
+      const prefix = rule.pattern.slice(0, -1);
+      if (branch.startsWith(prefix)) return rule;
+    } else if (branch === rule.pattern) {
+      return rule;
+    }
+  }
+  return void 0;
+}
+function resolveBranchDecision(options) {
+  const { strategy, identity } = options;
+  const channels = options.channels ?? [];
+  if (strategy === "legacy") {
+    return {
+      tier: "legacy",
+      strategy,
+      identity,
+      canonicalBranch: clean(options.canonicalBranch) ?? identity.defaultBranch,
+      reason: "branch-strategy legacy: branch-blind pre-v2 behavior"
+    };
+  }
+  const canonicalBranch = clean(options.canonicalBranch) ?? identity.defaultBranch;
+  if (!canonicalBranch) {
+    throw new ContractError(
+      "CONTRACT_DEFAULT_BRANCH_UNRESOLVED",
+      `cannot resolve the canonical branch on ${identity.provider} (no explicit canonical-branch input and the provider exposes no default-branch variable). Set the canonical-branch input.`
+    );
+  }
+  if (identity.refKind === "tag" || identity.refKind === "unknown" || !identity.headBranch) {
+    return {
+      tier: "gated",
+      strategy,
+      identity,
+      canonicalBranch,
+      reason: `ref kind ${identity.refKind}: never canonical/preview-eligible; no-op with annotation`
+    };
+  }
+  if (identity.headBranch === canonicalBranch) {
+    return {
+      tier: "canonical",
+      strategy,
+      identity,
+      canonicalBranch,
+      reason: `head branch equals canonical branch ${canonicalBranch}`
+    };
+  }
+  const channel = matchChannel(identity.headBranch, channels);
+  if (channel) {
+    return {
+      tier: "channel",
+      strategy,
+      identity,
+      canonicalBranch,
+      channel,
+      reason: `branch ${identity.headBranch} matches channel ${channel.pattern}=${channel.code}`
+    };
+  }
+  if (strategy === "preview") {
+    if (identity.isForkPr) {
+      return {
+        tier: "gated",
+        strategy,
+        identity,
+        canonicalBranch,
+        reason: "fork PR: preview-ineligible (same-repo gate), gated instead"
+      };
+    }
+    return {
+      tier: "preview",
+      strategy,
+      identity,
+      canonicalBranch,
+      reason: `branch ${identity.headBranch} under branch-strategy preview`
+    };
+  }
+  return {
+    tier: "gated",
+    strategy,
+    identity,
+    canonicalBranch,
+    reason: `branch ${identity.headBranch} under branch-strategy publish-gate`
+  };
+}
+var BRANCH_DECISION_ENV = "POSTMAN_BRANCH_DECISION";
+function serializeBranchDecision(decision) {
+  return JSON.stringify(decision);
+}
+function parseBranchDecision(raw) {
+  const value = clean(raw);
+  if (!value) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new ContractError("CONTRACT_BRANCH_DECISION_INVALID", "POSTMAN_BRANCH_DECISION is not valid JSON");
+  }
+  const candidate = parsed;
+  const tiers = ["canonical", "channel", "preview", "gated", "legacy"];
+  if (!candidate || typeof candidate !== "object" || !tiers.includes(candidate.tier) || !candidate.identity) {
+    throw new ContractError("CONTRACT_BRANCH_DECISION_INVALID", "POSTMAN_BRANCH_DECISION does not carry a valid BranchDecision");
+  }
+  return candidate;
+}
+function resolveEffectiveBranchDecision(options, env = process.env) {
+  const inherited = parseBranchDecision(env[BRANCH_DECISION_ENV]);
+  if (inherited) return inherited;
+  return resolveBranchDecision(options);
+}
+var PREVIEW_SLUG_MAX = 30;
+function buildBranchSlug(rawBranch) {
+  const sanitized = rawBranch.replace(/^refs\/heads\//, "").replace(/\s+/g, "-").replace(/[^A-Za-z0-9._-]/g, "-").replace(/-+/g, "-").replace(/^[._-]+|[._-]+$/g, "");
+  const truncated = sanitized.slice(0, PREVIEW_SLUG_MAX);
+  const lossy = truncated !== rawBranch.replace(/^refs\/heads\//, "");
+  if (!lossy) {
+    return { suffix: truncated, slug: truncated, lossy };
+  }
+  const hash = (0, import_node_crypto4.createHash)("sha256").update(rawBranch).digest("hex").slice(0, 6);
+  return { suffix: `${truncated}-${hash}`, slug: truncated, lossy };
+}
+function previewAssetName(baseName, rawBranch) {
+  return `${baseName} @${buildBranchSlug(rawBranch).suffix}`;
+}
+function channelAssetName(baseName, code) {
+  return `[${code}] ${baseName}`;
+}
+var MARKER_KEY = "x-pm-onboarding";
+function renderAssetMarker(marker) {
+  return `${MARKER_KEY}: ${JSON.stringify(marker)}`;
+}
+
 // node_modules/graphql/jsutils/inspect.mjs
 var MAX_ARRAY_LENGTH = 10;
 var MAX_RECURSIVE_DEPTH = 2;
@@ -305440,7 +306130,7 @@ function parseWsdl(content, opts) {
 }
 
 // src/lib/protocols/soap/builder.ts
-var import_node_crypto4 = require("node:crypto");
+var import_node_crypto5 = require("node:crypto");
 var COLLECTION_V210_SCHEMA2 = "https://schema.getpostman.com/json/collection/v2.1.0/collection.json";
 var SOAP11_ENVELOPE_NS = "http://schemas.xmlsoap.org/soap/envelope/";
 var SOAP12_ENVELOPE_NS = "http://www.w3.org/2003/05/soap-envelope";
@@ -305448,7 +306138,7 @@ var SOAP11_CONTENT_TYPE = "text/xml; charset=UTF-8";
 var SOAP12_CONTENT_TYPE = "application/soap+xml; charset=UTF-8";
 var WSA_NS = "http://www.w3.org/2005/08/addressing";
 function stableId2(seed) {
-  return (0, import_node_crypto4.createHash)("sha256").update(seed).digest("hex").slice(0, 32);
+  return (0, import_node_crypto5.createHash)("sha256").update(seed).digest("hex").slice(0, 32);
 }
 function envelopeNamespace(version) {
   return version === "1.2" ? SOAP12_ENVELOPE_NS : SOAP11_ENVELOPE_NS;
@@ -312211,6 +312901,11 @@ function resolveInputs(env = process.env) {
     ),
     protocolEndpointUrl: getInput2("protocol-endpoint-url", env),
     openapiVersion: resolveOpenapiVersion(getInput2("openapi-version", env)),
+    preserveOas30TypeNull: parseBooleanInput(
+      "preserve-oas30-type-null",
+      getInput2("preserve-oas30-type-null", env),
+      false
+    ),
     breakingChangeMode: parseBreakingChangeMode(getInput2("breaking-change-mode", env)),
     breakingBaselineSpecPath: getInput2("breaking-baseline-spec-path", env),
     breakingRulesPath: getInput2("breaking-rules-path", env) ?? bootstrapActionContract.inputs["breaking-rules-path"].default,
@@ -312241,8 +312936,71 @@ function resolveInputs(env = process.env) {
     githubRef: env.GITHUB_REF,
     githubSha: env.GITHUB_SHA,
     githubToken: getInput2("github-token", env) || env.GITHUB_TOKEN || "",
-    ghFallbackToken: getInput2("gh-fallback-token", env) || env.GH_FALLBACK_TOKEN || ""
+    ghFallbackToken: getInput2("gh-fallback-token", env) || env.GH_FALLBACK_TOKEN || "",
+    branchStrategy: parseEnumInput(
+      "branch-strategy",
+      getInput2("branch-strategy", env),
+      "legacy"
+    ),
+    canonicalBranch: getInput2("canonical-branch", env),
+    channels: getInput2("channels", env)
+  };
+}
+function decideBranchTier(inputs, env = process.env) {
+  return resolveEffectiveBranchDecision(
+    {
+      // Tolerate hand-built inputs objects (tests, embedders) that omit the
+      // field: absent means legacy, exactly like the action default.
+      strategy: inputs.branchStrategy ?? "legacy",
+      identity: resolveBranchIdentity(env, { defaultBranch: inputs.canonicalBranch }),
+      canonicalBranch: inputs.canonicalBranch,
+      channels: parseChannelRules(inputs.channels)
+    },
+    env
+  );
+}
+function embedSpecBranchMarker(content, decision, repo) {
+  if (decision.tier !== "preview" && decision.tier !== "channel" || !decision.identity.headBranch || !repo) {
+    return content;
+  }
+  const rawBranch = decision.identity.headBranch;
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const marker = {
+    repo,
+    rawBranch,
+    sanitizedBranch: rawBranch.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/-+/g, "-").slice(0, 30),
+    role: decision.tier,
+    headSha: decision.identity.headSha,
+    createdAt: now,
+    lastSyncedAt: now
   };
+  try {
+    if (content.trim().startsWith("{")) {
+      return `${JSON.stringify({ ...JSON.parse(content), "x-postman-onboarding": marker }, null, 2)}
+`;
+    }
+    const document2 = (0, import_yaml4.parse)(content);
+    if (!document2 || typeof document2 !== "object" || Array.isArray(document2)) return content;
+    return (0, import_yaml4.stringify)({ ...document2, "x-postman-onboarding": marker });
+  } catch {
+    return content;
+  }
+}
+function renderCollectionBranchMarker(decision, repo, now = /* @__PURE__ */ new Date()) {
+  if (decision.tier !== "preview" && decision.tier !== "channel" || !decision.identity.headBranch || !repo) {
+    return void 0;
+  }
+  const rawBranch = decision.identity.headBranch;
+  const timestamp = now.toISOString();
+  return renderAssetMarker({
+    repo,
+    rawBranch,
+    sanitizedBranch: rawBranch.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/-+/g, "-").slice(0, 30),
+    role: decision.tier,
+    headSha: decision.identity.headSha,
+    createdAt: timestamp,
+    lastSyncedAt: timestamp
+  });
 }
 function createPlannedOutputs(inputs) {
   const workspaceName = inputs.domainCode ? `[${inputs.domainCode}] ${inputs.projectName}` : inputs.projectName;
@@ -312275,7 +313033,12 @@ function createPlannedOutputs(inputs) {
       mode: inputs.breakingChangeMode,
       status: "skipped",
       summaryPath: ""
-    })
+    }),
+    "sync-status": "",
+    "branch-decision": "",
+    "spec-version-tag": "",
+    "spec-version-url": "",
+    "spec-content-changed": ""
   };
 }
 function warnIfDeprecatedAccessToken(actionCore, inputs) {
@@ -312312,9 +313075,6 @@ function readActionInputs(actionCore) {
   }
   const postmanApiKey = optionalInput(actionCore, "postman-api-key") ?? "";
   const postmanAccessToken = optionalInput(actionCore, "postman-access-token");
-  if (!postmanApiKey && !postmanAccessToken) {
-    throw new Error("One of postman-api-key or postman-access-token is required.");
-  }
   const githubToken = optionalInput(actionCore, "github-token") || process.env.GITHUB_TOKEN;
   const ghFallbackToken = optionalInput(actionCore, "gh-fallback-token") || process.env.GH_FALLBACK_TOKEN;
   if (postmanApiKey) actionCore.setSecret(postmanApiKey);
@@ -312358,6 +313118,7 @@ function readActionInputs(actionCore) {
     INPUT_NESTED_FOLDER_HIERARCHY: optionalInput(actionCore, "nested-folder-hierarchy") ?? bootstrapActionContract.inputs["nested-folder-hierarchy"].default,
     INPUT_REQUEST_NAME_SOURCE: optionalInput(actionCore, "request-name-source") ?? bootstrapActionContract.inputs["request-name-source"].default,
     INPUT_OPENAPI_VERSION: optionalInput(actionCore, "openapi-version") ?? "",
+    INPUT_PRESERVE_OAS30_TYPE_NULL: optionalInput(actionCore, "preserve-oas30-type-null") ?? bootstrapActionContract.inputs["preserve-oas30-type-null"].default,
     INPUT_BREAKING_CHANGE_MODE: optionalInput(actionCore, "breaking-change-mode") ?? bootstrapActionContract.inputs["breaking-change-mode"].default,
     INPUT_BREAKING_BASELINE_SPEC_PATH: optionalInput(actionCore, "breaking-baseline-spec-path"),
     INPUT_BREAKING_RULES_PATH: optionalInput(actionCore, "breaking-rules-path") ?? bootstrapActionContract.inputs["breaking-rules-path"].default,
@@ -312468,6 +313229,27 @@ async function lintSpecViaCli(dependencies, workspaceId, specId) {
     warnings
   };
 }
+function normalizeLintPath(value) {
+  return value.trim().replace(/^\$\.?/, "").replace(/\[(\d+)\]/g, ".$1").replace(/^\./, "");
+}
+function applyOas30TypeNullLintCompatibility(summary2, sourceTypeNullPaths) {
+  const acceptedPaths = new Set(sourceTypeNullPaths.map(normalizeLintPath));
+  if (acceptedPaths.size === 0) return summary2;
+  const violations = summary2.violations.map((violation) => {
+    const path10 = normalizeLintPath(violation.path ?? "");
+    const issue2 = violation.issue ?? "";
+    const isTypeEnumFinding = /["']?type["']? property/i.test(issue2) && /allowed values|must be equal to one of/i.test(issue2);
+    if (violation.severity === "ERROR" && acceptedPaths.has(path10) && isTypeEnumFinding) {
+      return { ...violation, severity: "WARNING" };
+    }
+    return violation;
+  });
+  return {
+    errors: violations.filter((entry) => entry.severity === "ERROR").length,
+    violations,
+    warnings: violations.filter((entry) => entry.severity === "WARNING").length
+  };
+}
 function shouldRetrySpecFetch(error2) {
   const retryability = classifySafeFetchRetryability(error2);
   return retryability === "retryable" || retryability === "unknown";
@@ -312948,7 +313730,7 @@ async function runProtocolBootstrap(specType, rawSpecContent, inputs, dependenci
     const workspaceRoot = path9.resolve(process.env.GITHUB_WORKSPACE ?? process.cwd());
     const serviceConfigPath = path9.join(path9.dirname(path9.resolve(workspaceRoot, inputs.specPath)), "grpc_service_config.json");
     try {
-      grpcServiceConfigJson = (0, import_node_fs5.readFileSync)(serviceConfigPath, "utf8");
+      grpcServiceConfigJson = (0, import_node_fs6.readFileSync)(serviceConfigPath, "utf8");
       dependencies.core.info(`Found gRPC service config at ${serviceConfigPath}; validating it against the proto contract`);
     } catch {
     }
@@ -312962,7 +313744,7 @@ async function runProtocolBootstrap(specType, rawSpecContent, inputs, dependenci
       const resolved = path9.resolve(specDir, location2);
       if (!resolved.startsWith(specDir + path9.sep)) return void 0;
       try {
-        return (0, import_node_fs5.readFileSync)(resolved, "utf8");
+        return (0, import_node_fs6.readFileSync)(resolved, "utf8");
       } catch {
         return void 0;
       }
@@ -313103,6 +313885,42 @@ async function createExtensibleContractCollection(workspaceId, built, inputs, de
 }
 async function runBootstrapInner(inputs, dependencies, telemetry) {
   const outputs = createPlannedOutputs(inputs);
+  const branchDecision = decideBranchTier(inputs);
+  const isCanonicalWriter = branchDecision.tier === "legacy" || branchDecision.tier === "canonical";
+  const canonicalProjectName = inputs.projectName;
+  const workspaceName = createWorkspaceName(inputs);
+  const aboutText = `Auto-provisioned by Postman for ${inputs.projectName}`;
+  if (branchDecision.tier === "preview" && branchDecision.identity.headBranch) {
+    inputs = {
+      ...inputs,
+      projectName: previewAssetName(inputs.projectName, branchDecision.identity.headBranch)
+    };
+    dependencies.core.info(`branch-aware sync: preview asset set "${inputs.projectName}"`);
+  } else if (branchDecision.tier === "channel" && branchDecision.channel) {
+    inputs = {
+      ...inputs,
+      projectName: channelAssetName(inputs.projectName, branchDecision.channel.code)
+    };
+    dependencies.core.info(`branch-aware sync: channel asset set "${inputs.projectName}"`);
+  }
+  const collectionBranchMarker = renderCollectionBranchMarker(branchDecision, inputs.repoUrl);
+  if (branchDecision.tier !== "legacy") {
+    outputs["sync-status"] = "synced";
+    outputs["branch-decision"] = serializeBranchDecision(branchDecision);
+  }
+  if (!isCanonicalWriter) {
+    const explicitCanonicalIds = [
+      ["spec-id", inputs.specId],
+      ["baseline-collection-id", inputs.baselineCollectionId],
+      ["smoke-collection-id", inputs.smokeCollectionId],
+      ["contract-collection-id", inputs.contractCollectionId]
+    ].filter(([, value]) => Boolean(value));
+    if (explicitCanonicalIds.length > 0) {
+      throw new Error(
+        `CONTRACT_BRANCH_CANONICAL_WRITE: a ${branchDecision.tier} run must not mutate canonical assets, but explicit asset id input(s) were provided: ${explicitCanonicalIds.map(([name]) => name).join(", ")}. Remove them (preview/channel runs discover or create their own suffixed asset sets).`
+      );
+    }
+  }
   const requiresReleaseLabel = inputs.collectionSyncMode === "version" || inputs.specSyncMode === "version";
   const releaseLabel = requiresReleaseLabel ? deriveReleaseLabel(inputs) : void 0;
   if (requiresReleaseLabel && !releaseLabel) {
@@ -313110,11 +313928,23 @@ async function runBootstrapInner(inputs, dependencies, telemetry) {
       "Versioned spec or collection sync requires a release-label or derivable GitHub ref metadata"
     );
   }
-  const collectionAssetProjectName = inputs.collectionSyncMode === "version" ? createAssetProjectName(inputs, releaseLabel) : inputs.projectName;
-  const workspaceName = createWorkspaceName(inputs);
-  const aboutText = `Auto-provisioned by Postman for ${inputs.projectName}`;
-  const stateStore = resolveResourcesStateStore(dependencies);
-  const resourcesState = stateStore.read();
+  const collectionAssetProjectName = branchDecision.tier === "channel" ? canonicalProjectName : inputs.collectionSyncMode === "version" ? createAssetProjectName(inputs, releaseLabel) : inputs.projectName;
+  const rawStateStore = resolveResourcesStateStore(dependencies);
+  const trackedState = rawStateStore.read();
+  const stateStore = isCanonicalWriter ? rawStateStore : {
+    read: rawStateStore.read,
+    write: () => {
+      dependencies.core.info(
+        `branch-aware sync: skipping .postman/resources.yaml write on ${branchDecision.tier} run (canonical-only tracked state)`
+      );
+    }
+  };
+  const resourcesState = isCanonicalWriter ? trackedState : trackedState?.workspace ? { workspace: trackedState.workspace } : null;
+  if (!isCanonicalWriter && trackedState?.cloudResources) {
+    dependencies.core.info(
+      "branch-aware sync: canonical asset ids in .postman/resources.yaml are not resolved on a non-canonical run"
+    );
+  }
   const writableResourcesState = resourcesState ?? {};
   const additionalCollections = loadAdditionalCollectionFiles(
     inputs.additionalCollectionsDir,
@@ -313134,16 +313964,19 @@ async function runBootstrapInner(inputs, dependencies, telemetry) {
   }
   let previousSpecContent;
   let previousSpecRollbackHash;
+  let specContentUnchanged = false;
   let detectedOpenapiVersion = "3.0";
   let contractIndex;
   let sourceSpecContent = "";
+  let sourceTypeNullPaths = [];
+  let preserveSourceSpecBytes = false;
   const rawSpecContent = await runGroup(
     dependencies.core,
     "Read API Spec",
     async () => {
       if (inputs.specPath) {
         const workspaceRoot = path9.resolve(process.env.GITHUB_WORKSPACE ?? process.cwd());
-        return (0, import_node_fs5.readFileSync)(path9.resolve(workspaceRoot, inputs.specPath), "utf8");
+        return (0, import_node_fs6.readFileSync)(path9.resolve(workspaceRoot, inputs.specPath), "utf8");
       }
       if (dependencies.specFetcher === fetch) {
         return safeFetchText(inputs.specUrl, { depth: 0 });
@@ -313179,6 +314012,7 @@ async function runBootstrapInner(inputs, dependencies, telemetry) {
       };
       const rootKey = inputs.specPath ? void 0 : normalizeRef(inputs.specUrl);
       const loaderOptions = {
+        preserveOas30TypeNull: Boolean(inputs.preserveOas30TypeNull),
         fetchText: async (url, fetchOptions) => {
           if (rootKey && normalizeRef(url) === rootKey) return rawSpecContent;
           if (dependencies.specFetcher === fetch) return safeFetchText(url, fetchOptions);
@@ -313187,6 +314021,8 @@ async function runBootstrapInner(inputs, dependencies, telemetry) {
       };
       const loaded = inputs.specPath ? await loadOpenApiContractSpecFromPath(inputs.specPath, loaderOptions) : await loadOpenApiContractSpec(inputs.specUrl, loaderOptions);
       sourceSpecContent = loaded.content;
+      sourceTypeNullPaths = loaded.sourceTypeNullPaths;
+      preserveSourceSpecBytes = sourceTypeNullPaths.length > 0;
       const document2 = normalizeSpecDocument(
         loaded.bundledContent,
         (msg) => dependencies.core.warning(msg)
@@ -313209,11 +314045,11 @@ async function runBootstrapInner(inputs, dependencies, telemetry) {
             `Unable to verify existing Spec Hub OpenAPI version for spec-id ${specId}; clear spec-id to create a fresh spec`
           );
         }
-        previousSpecContent = normalizeSpecDocument(
+        previousSpecContent = preserveSourceSpecBytes ? previousRaw : normalizeSpecDocument(
           previousRaw,
           (msg) => dependencies.core.warning(`Previous spec normalization: ${msg}`)
         );
-        previousSpecRollbackHash = (0, import_node_crypto5.createHash)("sha256").update(previousSpecContent).digest("hex");
+        previousSpecRollbackHash = (0, import_node_crypto6.createHash)("sha256").update(previousSpecContent).digest("hex");
         const existingSpecType = normalizeSpecTypeFromContent(previousSpecContent);
         if (existingSpecType !== incomingSpecType) {
           throw new Error(
@@ -313224,6 +314060,12 @@ async function runBootstrapInner(inputs, dependencies, telemetry) {
       dependencies.core.info(
         `Auto-detected OpenAPI version from spec content: ${detectedOpenapiVersion}`
       );
+      if (preserveSourceSpecBytes) {
+        dependencies.core.info(
+          `Preserving original OpenAPI source bytes; accepted ${sourceTypeNullPaths.length} legacy type: null member(s) for internal validation`
+        );
+        return loaded.content;
+      }
       return document2;
     }
   );
@@ -313259,6 +314101,11 @@ async function runBootstrapInner(inputs, dependencies, telemetry) {
       `OpenAPI breaking-change check failed: ${breakingChangeResult.message || "breaking changes detected"}`
     );
   }
+  const uploadSpecContent = embedSpecBranchMarker(
+    specContent,
+    branchDecision,
+    inputs.repoUrl
+  );
   const provisioned = await provisionWorkspace(
     inputs,
     dependencies,
@@ -313383,10 +314230,17 @@ async function runBootstrapInner(inputs, dependencies, telemetry) {
         specId ? "Update Spec in Spec Hub" : "Upload Spec to Spec Hub",
         async () => {
           if (specId) {
-            dependencies.core.info(
-              `Updating existing spec ${specId} (detected version: ${detectedOpenapiVersion}). Note: the spec type (OPENAPI:3.0 / OPENAPI:3.1) is set at creation and cannot be changed on update. If you changed OpenAPI versions, clear the spec-id input to create a fresh spec.`
-            );
-            await dependencies.postman.updateSpec(specId, specContent, workspaceId);
+            if (previousSpecContent !== void 0 && (0, import_node_crypto6.createHash)("sha256").update(uploadSpecContent).digest("hex") === (0, import_node_crypto6.createHash)("sha256").update(previousSpecContent).digest("hex")) {
+              specContentUnchanged = true;
+              dependencies.core.info(
+                `Spec content unchanged (sha256 match); skipping Spec Hub update and version tag for ${specId}.`
+              );
+            } else {
+              dependencies.core.info(
+                `Updating existing spec ${specId} (detected version: ${detectedOpenapiVersion}). Note: the spec type (OPENAPI:3.0 / OPENAPI:3.1) is set at creation and cannot be changed on update. If you changed OpenAPI versions, clear the spec-id input to create a fresh spec.`
+              );
+              await dependencies.postman.updateSpec(specId, uploadSpecContent, workspaceId);
+            }
           } else {
             specId = await dependencies.postman.uploadSpec(
               workspaceId || "",
@@ -313394,7 +314248,7 @@ async function runBootstrapInner(inputs, dependencies, telemetry) {
                 inputs,
                 inputs.specSyncMode === "version" ? releaseLabel : void 0
               ),
-              specContent,
+              uploadSpecContent,
               detectedOpenapiVersion
             );
           }
@@ -313411,8 +314265,9 @@ async function runBootstrapInner(inputs, dependencies, telemetry) {
         }
       )
     );
+    outputs["spec-content-changed"] = isCanonicalWriter && !specContentUnchanged ? "true" : "false";
     if (lintEnabled) {
-      const lintSummary = await runRollbackStage(
+      let lintSummary = await runRollbackStage(
         "Lint Spec via Postman CLI",
         async () => runGroup(
           dependencies.core,
@@ -313420,6 +314275,16 @@ async function runBootstrapInner(inputs, dependencies, telemetry) {
           async () => lintSpecViaCli(dependencies, workspaceId || "", outputs["spec-id"])
         )
       );
+      if (preserveSourceSpecBytes) {
+        const originalErrorCount = lintSummary.errors;
+        lintSummary = applyOas30TypeNullLintCompatibility(lintSummary, sourceTypeNullPaths);
+        const acceptedCount = originalErrorCount - lintSummary.errors;
+        if (acceptedCount > 0) {
+          dependencies.core.info(
+            `Accepted ${acceptedCount} Postman CLI type: null finding(s) covered by preserve-oas30-type-null`
+          );
+        }
+      }
       outputs["lint-summary-json"] = JSON.stringify({
         errors: lintSummary.errors,
         total: lintSummary.violations.length,
@@ -313444,7 +314309,12 @@ async function runBootstrapInner(inputs, dependencies, telemetry) {
       });
       dependencies.core.warning("lint skipped: governance errors not enforced (no postman-api-key)");
     }
-    await runRollbackStage(
+    if (specContentUnchanged) {
+      outputs["baseline-collection-id"] = baselineCollectionId || "";
+      outputs["smoke-collection-id"] = smokeCollectionId || "";
+      outputs["contract-collection-id"] = contractCollectionId || "";
+      dependencies.core.info("Spec content unchanged; skipping collection regeneration and version finalization.");
+    } else await runRollbackStage(
       "Generate Collections from Spec",
       async () => runGroup(
         dependencies.core,
@@ -313483,10 +314353,11 @@ async function runBootstrapInner(inputs, dependencies, telemetry) {
                 return;
               }
             }
+            const effectivePrefix = branchDecision.tier === "channel" && branchDecision.channel ? channelAssetName(prefix, branchDecision.channel.code).trim() : prefix;
             outputs[outputKey] = await dependencies.postman.generateCollection(
               specId2,
               assetProjectName,
-              prefix,
+              effectivePrefix,
               inputs.folderStrategy,
               inputs.nestedFolderHierarchy,
               inputs.requestNameSource
@@ -313507,6 +314378,32 @@ async function runBootstrapInner(inputs, dependencies, telemetry) {
           await ensureCollection(BASELINE_COLLECTION_PREFIX, baselineCollectionId, "baseline-collection-id");
           await ensureCollection(SMOKE_COLLECTION_PREFIX, smokeCollectionId, "smoke-collection-id");
           await ensureCollection(CONTRACT_COLLECTION_PREFIX, contractCollectionId, "contract-collection-id");
+          if (dependencies.postman.adoptGeneratedCollection) {
+            const reelect = async (prefix, outputKey) => {
+              const effectivePrefix = branchDecision.tier === "channel" && branchDecision.channel ? channelAssetName(prefix, branchDecision.channel.code).trim() : prefix;
+              const preferred = outputs[outputKey];
+              if (!preferred) return;
+              outputs[outputKey] = await dependencies.postman.adoptGeneratedCollection(
+                specId2,
+                assetProjectName,
+                effectivePrefix,
+                preferred
+              );
+            };
+            await reelect(BASELINE_COLLECTION_PREFIX, "baseline-collection-id");
+            await reelect(SMOKE_COLLECTION_PREFIX, "smoke-collection-id");
+            await reelect(CONTRACT_COLLECTION_PREFIX, "contract-collection-id");
+          }
+          if (collectionBranchMarker) {
+            if (!dependencies.postman.updateCollectionDescription) {
+              throw new Error("Branch-scoped collections require updateCollectionDescription support");
+            }
+            await Promise.all([
+              outputs["baseline-collection-id"],
+              outputs["smoke-collection-id"],
+              outputs["contract-collection-id"]
+            ].filter(Boolean).map((id) => dependencies.postman.updateCollectionDescription(id, collectionBranchMarker)));
+          }
           if (!dependencies.postman.injectContractTests) {
             throw new Error(
               "Dynamic contract tests require injectContractTests support from the access-token gateway client"
@@ -313609,6 +314506,12 @@ async function runBootstrapInner(inputs, dependencies, telemetry) {
               workspaceId: workspaceId || ""
             });
             for (const result of additionalResults) {
+              if (collectionBranchMarker) {
+                if (!dependencies.postman.updateCollectionDescription) {
+                  throw new Error("Branch-scoped collections require updateCollectionDescription support");
+                }
+                await dependencies.postman.updateCollectionDescription(result.collectionId, collectionBranchMarker);
+              }
               completedExternalSideEffects.push(
                 `${result.operation}AdditionalCollection(${result.collectionId} from ${result.displayPath})`
               );
@@ -313684,8 +314587,66 @@ async function runBootstrapInner(inputs, dependencies, telemetry) {
   }
   return outputs;
 }
+async function runGatedValidation(inputs, decision, actionCore) {
+  actionCore.info(`branch-aware sync: gated run (${decision.reason}) \u2014 credential-free static validation, zero workspace writes`);
+  const outputs = createPlannedOutputs(inputs);
+  outputs["sync-status"] = "skipped-branch-gate";
+  outputs["branch-decision"] = serializeBranchDecision(decision);
+  let violations = [];
+  let validated = false;
+  try {
+    let content;
+    if (inputs.specPath) {
+      content = (0, import_node_fs6.readFileSync)(inputs.specPath, "utf8");
+    } else if (inputs.specUrl) {
+      content = await safeFetchText(inputs.specUrl, { depth: 0 });
+    }
+    if (content) {
+      const specType = detectSpecType(content, inputs.specPath);
+      if (specType === "openapi") {
+        const document2 = parseOpenApiDocument(content);
+        const index = buildContractIndex(document2);
+        violations = index.warnings;
+        validated = true;
+      } else {
+        actionCore.info(`branch gate: static lint for spec type ${specType} runs through its protocol builder on publish; parse-only gate applied`);
+        validated = true;
+      }
+    } else {
+      actionCore.info("branch gate: no spec-url/spec-path provided; nothing to validate");
+    }
+  } catch (error2) {
+    throw new Error(
+      `branch gate: static validation failed: ${error2 instanceof Error ? error2.message : String(error2)}`,
+      { cause: error2 }
+    );
+  }
+  outputs["lint-summary-json"] = JSON.stringify({
+    status: validated ? "static-only" : "skipped",
+    reason: "branch-gated run: governance lint requires upload and runs on publish/preview syncs",
+    errors: 0,
+    warnings: violations.length,
+    total: violations.length,
+    violations: violations.map((issue2) => ({ issue: issue2, severity: "WARNING" }))
+  });
+  for (const [name, value] of Object.entries(outputs)) {
+    actionCore.setOutput(name, value);
+  }
+  return outputs;
+}
 async function runAction(actionCore = core_exports, actionExec = exec_exports, actionIo = io_exports) {
   const inputs = readActionInputs(actionCore);
+  const branchDecision = decideBranchTier(inputs);
+  if (branchDecision.tier === "gated") {
+    return runGatedValidation(inputs, branchDecision, actionCore);
+  }
+  if (!inputs.postmanApiKey && !inputs.postmanAccessToken) {
+    throw new Error("One of postman-api-key or postman-access-token is required for a writing sync.");
+  }
+  if (branchDecision.tier !== "legacy") {
+    actionCore.info(`branch-aware sync: tier=${branchDecision.tier} (${branchDecision.reason})`);
+    process.env[BRANCH_DECISION_ENV] = serializeBranchDecision(branchDecision);
+  }
   await mintAccessTokenIfNeeded2(inputs, {
     info: (message) => actionCore.info(message),
     warning: (message) => actionCore.warning(message)
@@ -313762,6 +314723,7 @@ function createRoutingPostmanClient(options) {
       updateSpec: requireAccessToken("updateSpec"),
       getSpecContent: requireAccessToken("getSpecContent"),
       generateCollection: requireAccessToken("generateCollection"),
+      adoptGeneratedCollection: requireAccessToken("adoptGeneratedCollection"),
       createWorkspace: requireAccessToken("createWorkspace"),
       getWorkspaceVisibility: requireAccessToken("getWorkspaceVisibility"),
       getWorkspaceGitRepoUrl: requireAccessToken("getWorkspaceGitRepoUrl"),
@@ -313771,10 +314733,13 @@ function createRoutingPostmanClient(options) {
       inviteRequesterToWorkspace: requireAccessToken("inviteRequesterToWorkspace"),
       injectTests: requireAccessToken("injectTests"),
       tagCollection: requireAccessToken("tagCollection"),
+      tagSpecVersion: requireAccessToken("tagSpecVersion"),
+      listSpecVersionTags: requireAccessToken("listSpecVersionTags"),
       deleteCollection: requireAccessToken("deleteCollection"),
       injectContractTests: requireAccessToken("injectContractTests"),
       createCollection: requireAccessToken("createCollection"),
-      updateCollection: requireAccessToken("updateCollection")
+      updateCollection: requireAccessToken("updateCollection"),
+      updateCollectionDescription: requireAccessToken("updateCollectionDescription")
     };
   }
   return {
@@ -313786,6 +314751,7 @@ function createRoutingPostmanClient(options) {
     // not a reason to reach for the API key.
     uploadSpec: (workspaceId, projectName, specContent, openapiVersion) => gateway.uploadSpec(workspaceId, projectName, specContent, openapiVersion ?? "3.0"),
     generateCollection: (specId, projectName, prefix, folderStrategy, nestedFolderHierarchy, requestNameSource) => gateway.generateCollection(specId, projectName, prefix, folderStrategy, nestedFolderHierarchy, requestNameSource),
+    adoptGeneratedCollection: (specId, projectName, prefix, preferredId) => gateway.adoptGeneratedCollection(specId, projectName, prefix, preferredId),
     updateSpec: (specId, specContent, workspaceId) => gateway.updateSpec(specId, specContent, workspaceId),
     getSpecContent: (specId) => gateway.getSpecContent(specId),
     createWorkspace: (name, about, targetTeamId) => gateway.createWorkspace(name, about, targetTeamId),
@@ -313797,6 +314763,8 @@ function createRoutingPostmanClient(options) {
     // + tagging surfaces (live-proven). PMAK is reserved for token minting, so
     // these never fall back to the API key even when one is present.
     injectTests: (collectionId, type) => gateway.injectTests(collectionId, type),
+    tagSpecVersion: (specId, name) => gateway.tagSpecVersion(specId, name),
+    listSpecVersionTags: (specId) => gateway.listSpecVersionTags(specId),
     tagCollection: (collectionId, tags) => gateway.tagCollection(collectionId, tags),
     // Sub-team (squad) enumeration over the gateway `ums` service. Access-token
     // only — never PMAK — so org-mode detection no longer needs a PMAK GET /teams.
@@ -313814,7 +314782,8 @@ function createRoutingPostmanClient(options) {
     // so no asset op ever reaches for the API key.
     injectContractTests: (collectionUid, index) => gateway.injectContractTests(collectionUid, index),
     createCollection: (workspaceId, collection, options2) => gateway.createCollection(workspaceId, collection, options2),
-    updateCollection: (collectionUid, collection) => gateway.updateCollection(collectionUid, collection)
+    updateCollection: (collectionUid, collection) => gateway.updateCollection(collectionUid, collection),
+    updateCollectionDescription: (collectionUid, description) => gateway.updateCollectionDescription(collectionUid, description)
   };
 }
 function createBootstrapDependencies(inputs, factories, orgMode = false) {